@ngockhoale/ukit 1.1.6

package/templates/.claude/skills/docs-manager/SKILL.md

@@ -0,0 +1,465 @@
+---
+name: docs-manager
+description: Standardized documentation workflow for template-based projects.
+---
+
+# Documentation Manager Skill
+
+> Skill này giúp AI agents làm việc với docs chuẩn hóa trong mọi project
+
+## When to Use This Skill
+
+AI agent NÊN dùng skill này khi:
+
+- 🆕 Bắt đầu làm việc với project mới
+- 📖 Cần hiểu cấu trúc và quy tắc của project
+- 🏗️ Đưa ra quyết định về kiến trúc
+- 🐛 Debug vấn đề phức tạp
+- 🤝 Handoff giữa các agents
+- 📝 Cập nhật documentation
+
+## Documentation Structure
+
+Mọi project sử dụng skill này PHẢI có folder `docs/` với cấu trúc:
+
+```
+docs/
+├── README.md                    # 🎯 BẮT ĐẦU TẠI ĐÂY - Navigation hub
+├── project.md                   # 📋 Project overview
+├── memory.md                    # 🧠 Decisions & context log
+│
+├── architecture/                # 🏗️ System design
+│   ├── overview.md             # Architecture tổng quan
+│   ├── tech-stack.md           # Technologies sử dụng
+│   ├── data-model.md           # Database schema
+│   ├── api-design.md           # API specifications
+│   └── deployment.md           # Infrastructure
+│
+├── agents/                      # 🤖 Multi-agent coordination
+│   ├── agent-roles.md          # Vai trò từng agent
+│   ├── orchestration.md        # Flow điều phối
+│   ├── prompts/                # System prompts
+│   │   ├── architect.md
+│   │   ├── coder.md
+│   │   ├── debugger.md
+│   │   └── orchestrator.md
+│   └── handoff-rules.md        # Quy tắc chuyển giao
+│
+├── standards/                   # 📏 Coding standards
+│   ├── coding-conventions.md   # Code style
+│   ├── commit-conventions.md   # Git conventions
+│   ├── file-structure.md       # File organization
+│   ├── error-handling.md       # Error handling
+│   └── security.md             # Security rules
+│
+├── workflows/                   # 🔄 Development processes
+│   ├── development.md          # Feature development flow
+│   ├── debugging.md            # Debug process
+│   ├── testing.md              # Testing strategy
+│   ├── deployment.md           # Deployment process
+│   └── code-review.md          # Review checklist
+│
+├── context/                     # 📚 Business context
+│   ├── business-rules.md       # Business logic
+│   ├── constraints.md          # Technical constraints
+│   ├── dependencies.md         # External dependencies
+│   └── known-issues.md         # Known issues & workarounds
+│
+├── guides/                      # 📖 How-to guides
+│   ├── onboarding.md           # AI onboarding
+│   ├── quick-start.md          # Quick setup
+│   ├── troubleshooting.md      # Common problems
+│   └── faq.md                  # FAQs
+│
+└── models/                      # 🧠 AI model configs
+    ├── model-configs.md        # Model configurations
+    ├── model-selection.md      # When to use which model
+    ├── token-optimization.md   # Token optimization
+    └── fallback-strategy.md    # Fallback handling
+```
+
+## Workflow: How AI Should Use This Skill
+
+### 🎬 Phase 1: Initial Context Loading (LUÔN LÀM ĐẦU TIÊN)
+
+**Khi bắt đầu với project mới hoặc conversation mới:**
+
+```bash
+# Bước 1: Đọc README.md - Entry point
+cat docs/README.md
+
+# Bước 2: Hiểu project
+cat docs/project.md
+
+# Bước 3: Load context
+cat docs/memory.md
+
+# Bước 4: Xác định vai trò
+cat docs/agents/agent-roles.md
+```
+
+**Output mong đợi sau Phase 1:**
+
+- ✅ Hiểu project làm gì
+- ✅ Biết tech stack
+- ✅ Nắm được decisions quan trọng
+- ✅ Xác định được vai trò của mình
+
+---
+
+### 🛠️ Phase 2: Task-Specific Preparation
+
+**Tùy vào task type, đọc thêm:**
+
+#### Nếu task = "Develop feature mới"
+
+```bash
+cat docs/architecture/overview.md
+cat docs/architecture/data-model.md
+cat docs/standards/coding-conventions.md
+cat docs/workflows/development.md
+```
+
+#### Nếu task = "Fix bug"
+
+```bash
+cat docs/context/known-issues.md
+cat docs/guides/troubleshooting.md
+cat docs/workflows/debugging.md
+cat docs/memory.md  # Tìm cases tương tự
+```
+
+#### Nếu task = "Design architecture"
+
+```bash
+cat docs/architecture/overview.md
+cat docs/context/constraints.md
+cat docs/context/business-rules.md
+cat docs/standards/coding-conventions.md
+```
+
+#### Nếu task = "Review code"
+
+```bash
+cat docs/standards/coding-conventions.md
+cat docs/workflows/code-review.md
+cat docs/architecture/data-model.md
+```
+
+---
+
+### ✍️ Phase 3: Execution
+
+**Trong quá trình làm:**
+
+1. **Tuân thủ standards**
+   - Luôn follow `docs/standards/coding-conventions.md`
+   - Check `docs/architecture/data-model.md` khi làm việc với DB
+   - Apply `docs/standards/error-handling.md`
+
+2. **Document decisions**
+   - Quyết định quan trọng → ghi vào `docs/memory.md`
+   - Phát hiện issue mới → ghi vào `docs/context/known-issues.md`
+   - Thay đổi architecture → update `docs/architecture/`
+
+3. **Cross-check context**
+   - Trước khi implement → check `docs/context/constraints.md`
+   - Không chắc business logic → check `docs/context/business-rules.md`
+
+---
+
+### 🔄 Phase 4: Handoff & Documentation
+
+**Trước khi handoff hoặc kết thúc task:**
+
+1. **Update memory.md**
+
+```markdown
+## [2025-01-24] - [Task Title]
+
+**Context**: Làm gì? Tại sao?
+**Decision**: Quyết định quan trọng nào?
+**Impact**: Ảnh hưởng đến đâu?
+**Next Steps**: Cần làm gì tiếp?
+```
+
+2. **Update relevant docs**
+   - Architecture changed? → Update `docs/architecture/`
+   - New convention? → Update `docs/standards/`
+   - Found issue? → Update `docs/context/known-issues.md`
+
+3. **Prepare handoff**
+   - Summarize work done
+   - Document blockers/questions
+   - Point to relevant docs sections
+
+---
+
+## Key Principles
+
+### ✅ DO (LUÔN LÀM)
+
+1. **Đọc docs TRƯỚC KHI code**
+   - README.md → project.md → memory.md → standards/
+   - Không bao giờ skip bước này
+
+2. **Follow conventions NGHIÊM NGẶT**
+   - Code style from `standards/coding-conventions.md`
+   - Database rules from `architecture/data-model.md`
+   - Git commits from `standards/commit-conventions.md`
+
+3. **Document EVERYTHING quan trọng**
+   - Decisions → memory.md
+   - Issues → context/known-issues.md
+   - Architecture changes → architecture/
+
+4. **Cross-reference docs**
+   - Khi đọc 1 file, note references đến files khác
+   - Build mental map của toàn bộ docs
+
+5. **Update proactively**
+   - Tìm thấy thông tin mới? Update docs ngay
+   - Không để docs outdated
+
+### ❌ DON'T (TUYỆT ĐỐI TRÁNH)
+
+1. **Không skip đọc docs**
+   - Đừng assume bạn biết project
+   - Đừng code trước khi đọc conventions
+
+2. **Không violate conventions**
+   - Không tự ý thay đổi code style
+   - Không bỏ qua architecture constraints
+
+3. **Không quên document**
+   - Không để decisions chỉ trong chat
+   - Không quên update memory.md
+
+4. **Không duplicate info**
+   - Check docs trước khi thêm mới
+   - Consolidate thay vì scatter
+
+---
+
+## Code Conventions (From docs/standards/coding-conventions.md)
+
+### Database Rules
+
+```javascript
+// ✅ ĐÚNG: UUID primary keys
+id: {
+  type: DataTypes.UUID,
+  defaultValue: DataTypes.UUIDV4,
+  primaryKey: true
+}
+
+// ❌ SAI: Auto-increment
+id: {
+  type: DataTypes.INTEGER,
+  autoIncrement: true,
+  primaryKey: true
+}
+
+// ✅ ĐÚNG: No foreign key constraints
+user_id: {
+  type: DataTypes.UUID,
+  allowNull: false
+}
+
+// ❌ SAI: With FK constraint
+user_id: {
+  type: DataTypes.UUID,
+  references: { model: 'users', key: 'id' }
+}
+```
+
+### Oracle Schema Prefix
+
+```sql
+-- ✅ ĐÚNG: With schema prefix
+SELECT * FROM APPS.MTL_SYSTEM_ITEMS_B
+
+-- ❌ SAI: Without prefix
+SELECT * FROM MTL_SYSTEM_ITEMS_B
+```
+
+### Naming Conventions
+
+```javascript
+// Variables & Functions: camelCase
+const userName = "LeNK";
+function getUserData() {}
+
+// Classes: PascalCase
+class UserService {}
+
+// Constants: UPPER_SNAKE_CASE
+const API_BASE_URL = "https://api.example.com";
+
+// Files: kebab-case
+user - service.js;
+
+// DB tables/columns: snake_case
+(users, user_profiles, created_at);
+```
+
+---
+
+## Agent Coordination
+
+### Agent Roles (From docs/agents/agent-roles.md)
+
+**Architect Agent**
+
+- Design system architecture
+- Make technical decisions
+- Review architectural changes
+
+**Coder Agent**
+
+- Implement features
+- Write tests
+- Follow coding standards
+
+**Debugger Agent**
+
+- Analyze bugs
+- Find root causes
+- Verify fixes
+
+**Orchestrator Agent**
+
+- Break down tasks
+- Coordinate agents
+- Track progress
+
+### Handoff Rules
+
+**Khi nào handoff?**
+
+- Architect → Coder: Sau khi design xong
+- Coder → Debugger: Khi gặp bug
+- Debugger → Architect: Bug do design issue
+- Any → Orchestrator: Task phức tạp cần break down
+
+**Trước khi handoff:**
+
+1. Update `docs/memory.md` với context
+2. Summarize work done
+3. List blockers/questions
+4. Point to relevant docs
+
+---
+
+## Examples
+
+### Example 1: Starting New Feature
+
+```bash
+# User request: "Add user authentication"
+
+# Step 1: Load context
+cat docs/README.md
+cat docs/project.md
+cat docs/memory.md
+
+# Step 2: Check if similar feature exists
+grep -r "authentication" docs/memory.md
+cat docs/context/known-issues.md
+
+# Step 3: Load relevant docs
+cat docs/architecture/overview.md
+cat docs/architecture/data-model.md
+cat docs/standards/coding-conventions.md
+cat docs/standards/security.md
+
+# Step 4: Check workflows
+cat docs/workflows/development.md
+
+# Step 5: Start development following conventions
+
+# Step 6: Document decision
+echo "## [2025-01-24] - User Authentication
+**Context**: Need secure user auth
+**Decision**: Using bcrypt + JWT
+**Impact**: New users table, auth middleware
+**Next**: Implement signup/login endpoints" >> docs/memory.md
+```
+
+### Example 2: Debugging Issue
+
+```bash
+# User: "PostgreSQL auto-increment not working"
+
+# Step 1: Check known issues
+cat docs/context/known-issues.md
+
+# Step 2: Check conventions
+cat docs/standards/coding-conventions.md
+# → Found: We use UUID, not auto-increment!
+
+# Step 3: Check memory for similar cases
+grep -r "auto-increment\|UUID" docs/memory.md
+
+# Step 4: Provide solution based on conventions
+# Step 5: Update docs if needed
+```
+
+---
+
+## Initialization: Setting Up Docs for New Project
+
+**Nếu project CHƯA có docs/, tạo từ template:**
+
+```bash
+# Create structure
+mkdir -p docs/{architecture,agents/prompts,standards,workflows,context,guides,models}
+
+# Create essential files
+touch docs/{README.md,project.md,memory.md}
+touch docs/agents/agent-roles.md
+touch docs/standards/coding-conventions.md
+touch docs/guides/onboarding.md
+
+# Copy templates from this skill
+# (Templates sẽ có trong skill folder)
+```
+
+---
+
+## Success Metrics
+
+Skill hoạt động tốt khi:
+
+- ✅ AI onboard project < 5 phút
+- ✅ Code consistent theo standards
+- ✅ Ít questions lặp lại
+- ✅ Decisions được document đầy đủ
+- ✅ Handoff giữa agents mượt mà
+- ✅ Docs luôn up-to-date
+
+---
+
+## Troubleshooting
+
+### Problem: Docs outdated
+
+**Solution**: Đọc `docs/memory.md` - decision gần nhất là gì?
+
+### Problem: Không biết dùng agent nào
+
+**Solution**: Đọc `docs/agents/agent-roles.md`
+
+### Problem: Không biết convention
+
+**Solution**: Đọc `docs/standards/coding-conventions.md`
+
+### Problem: Business logic không rõ
+
+**Solution**: Đọc `docs/context/business-rules.md`
+
+---
+
+**Last Updated**: 2025-01-24
+**Version**: 1.0.0
+**Maintained by**: LeNK

package/templates/.claude/skills/docs-manager/init-project-docs.sh

@@ -0,0 +1,70 @@
+#!/bin/bash
+
+# Script khởi tạo docs cho project mới
+# Usage: ./init-project-docs.sh "Project Name"
+
+PROJECT_NAME=${1:-"New Project"}
+AUTHOR=${2:-$(git config user.name 2>/dev/null || echo "Developer")}
+DATE=$(date +%Y-%m-%d)
+
+echo "🚀 Initializing docs for: $PROJECT_NAME"
+echo "📅 Date: $DATE"
+echo "👤 Author: $AUTHOR"
+echo ""
+
+# Kiểm tra đã có docs/ chưa
+if [ -d "./docs" ]; then
+    echo "⚠️  Warning: docs/ folder already exists!"
+    read -p "Overwrite? (y/N): " -n 1 -r
+    echo
+    if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+        echo "❌ Cancelled"
+        exit 1
+    fi
+    rm -rf ./docs
+fi
+
+# Tạo cấu trúc
+echo "📁 Creating folder structure..."
+mkdir -p docs/{architecture,agents/prompts,standards,workflows,context,guides,models,integrations}
+
+# Copy templates
+SKILL_DIR="$HOME/.claude/skills/docs-manager/templates"
+
+echo "📄 Creating files from templates..."
+
+# Function replace placeholders
+replace_placeholders() {
+    local file=$1
+    sed "s/{{PROJECT_NAME}}/$PROJECT_NAME/g; s/{{AUTHOR}}/$AUTHOR/g; s/{{DATE}}/$DATE/g" "$file"
+}
+
+# Copy và replace
+replace_placeholders "$SKILL_DIR/README.md.template" > docs/README.md
+replace_placeholders "$SKILL_DIR/project.md.template" > docs/project.md
+replace_placeholders "$SKILL_DIR/memory.md.template" > docs/memory.md
+replace_placeholders "$SKILL_DIR/agent-roles.md.template" > docs/agents/agent-roles.md
+replace_placeholders "$SKILL_DIR/coding-conventions.md.template" > docs/standards/coding-conventions.md
+replace_placeholders "$SKILL_DIR/onboarding.md.template" > docs/guides/onboarding.md
+
+# Tạo empty files
+echo "📝 Creating placeholder files..."
+touch docs/architecture/{overview,tech-stack,data-model,api-design,deployment}.md
+touch docs/agents/{orchestration,handoff-rules}.md
+touch docs/agents/prompts/{architect,coder,debugger,orchestrator}.md
+touch docs/standards/{commit-conventions,file-structure,error-handling,security}.md
+touch docs/workflows/{development,debugging,testing,deployment,code-review}.md
+touch docs/context/{business-rules,constraints,dependencies,known-issues}.md
+touch docs/guides/{quick-start,troubleshooting,faq}.md
+touch docs/models/{model-configs,model-selection,token-optimization,fallback-strategy}.md
+touch docs/integrations/.gitkeep
+
+echo ""
+echo "✅ Docs initialized successfully!"
+echo ""
+echo "📝 Next steps:"
+echo "  1. Edit docs/project.md - Add project details"
+echo "  2. Edit docs/standards/coding-conventions.md - Customize conventions"
+echo "  3. Edit docs/architecture/overview.md - Document architecture"
+echo ""
+echo "🤖 AI agents can now read docs/ to understand your project!"

package/templates/.claude/skills/docs-manager/templates/README.md.template

@@ -0,0 +1,50 @@
+# 🤖 AI Documentation Hub
+
+> **Project**: {{PROJECT_NAME}}
+
+## 📖 BẮT ĐẦU TẠI ĐÂY
+
+### Bước 1: Hiểu dự án
+1. `project.md` - Mission & overview
+2. `memory.md` - Context & decisions
+3. `architecture/overview.md` - System design
+
+### Bước 2: Hiểu vai trò
+- `agents/agent-roles.md` - Vai trò của bạn
+- `agents/orchestration.md` - Phối hợp agents
+
+### Bước 3: Tuân thủ standards
+- `standards/coding-conventions.md` - PHẢI đọc
+- `standards/file-structure.md` - Tổ chức code
+
+## 🎯 Quick Reference
+
+**Bắt đầu task mới:**
+```
+1. Đọc memory.md
+2. Đọc context/business-rules.md
+3. Đọc architecture/data-model.md
+4. Follow standards/
+5. Theo workflows/development.md
+```
+
+**Gặp vấn đề:**
+```
+1. context/known-issues.md
+2. guides/troubleshooting.md
+3. memory.md
+4. workflows/debugging.md
+```
+
+## 📊 Cấu trúc
+
+- `/architecture` - System design
+- `/agents` - Multi-agent setup
+- `/standards` - Conventions
+- `/workflows` - Processes
+- `/context` - Business logic
+- `/guides` - How-to
+- `/models` - AI configs
+
+---
+**Version**: 1.0.0 | **Updated**: {{DATE}}

package/templates/.claude/skills/docs-manager/templates/agent-roles.md.template

@@ -0,0 +1,24 @@
+# AI Agent Roles
+
+## 🎭 Agents
+
+### Architect
+**Role**: Design & decisions
+**When**: New features, refactoring
+
+### Coder
+**Role**: Implementation
+**When**: After design approved
+
+### Debugger
+**Role**: Fix issues
+**When**: Bugs, failures
+
+### Orchestrator
+**Role**: Coordination
+**When**: Complex tasks
+
+## 🔄 Flow
+```
+Request → Orchestrator → Architect → Coder → Debugger
+```

package/templates/.claude/skills/docs-manager/templates/coding-conventions.md.template

@@ -0,0 +1,28 @@
+# Coding Conventions
+
+## 📦 Database
+- Primary Keys: UUID VARCHAR
+- Foreign Keys: No constraints
+- Naming: snake_case
+- Schema prefix: Required for Postgres
+
+## 💻 Code Style
+- Variables: camelCase
+- Classes: PascalCase
+- Constants: UPPER_SNAKE_CASE
+- Files: kebab-case
+
+## 🔒 Security
+- Hash: SHA-256 minimum
+- No hardcoded secrets
+- Use env variables
+
+## 📝 Comments
+- Explain WHY not WHAT
+- Update with code
+- No obvious comments
+
+## ✅ Errors
+- Try-catch async ops
+- Log properly
+- No silent fails

package/templates/.claude/skills/docs-manager/templates/memory.md.template

@@ -0,0 +1,30 @@
+# Project Memory
+
+## 🧠 Decisions
+
+### [{{DATE}}] - Project Init
+**Context**: Khởi tạo project
+**Decision**: Setup docs structure theo .claude skill
+**Impact**: Standardized documentation
+**Next**: Start development
+
+---
+
+## 📝 Notes
+
+### [{{DATE}}] - Setup Complete
+**What**: Docs structure ready
+**Why**: Enable AI collaboration
+**Reference**: ~/.claude/skills/docs-manager
+
+---
+
+## ⚠️ Known Issues
+
+(Chưa có)
+
+---
+
+## 🎓 Lessons
+
+(Sẽ update)

package/templates/.claude/skills/docs-manager/templates/onboarding.md.template

@@ -0,0 +1,20 @@
+# AI Onboarding
+
+## 🚀 5-Minute Start
+
+1. Read `README.md`
+2. Read `project.md`
+3. Read `memory.md`
+4. Read `agents/agent-roles.md`
+5. Read `standards/coding-conventions.md`
+
+## ✅ Checklist
+- [ ] Hiểu project?
+- [ ] Biết vai trò?
+- [ ] Nắm conventions?
+- [ ] Biết khi nào handoff?
+
+## 🆘 Help
+1. `guides/troubleshooting.md`
+2. `memory.md`
+3. Ask Orchestrator