apero-kit-cli 1.0.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apero-kit-cli",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "CLI tool to scaffold AI agent projects with pre-configured kits (Claude, OpenCode, Codex)",
   "type": "module",
   "bin": {
@@ -22,6 +22,7 @@
   "files": [
     "bin",
     "src",
+    "templates",
     "README.md",
     "LICENSE"
   ],

package/src/commands/init.js

@@ -114,9 +114,12 @@ export async function initCommand(projectName, options) {
 
   console.log('');
 
-  if (!await promptConfirm('Proceed?')) {
-    console.log(chalk.yellow('Cancelled.'));
-    return;
+  // Skip confirmation if --force is set
+  if (!options.force) {
+    if (!await promptConfirm('Proceed?')) {
+      console.log(chalk.yellow('Cancelled.'));
+      return;
+    }
   }
 
   // 7. Create project

package/src/utils/paths.js

@@ -9,6 +9,9 @@ const __dirname = dirname(__filename);
 // CLI root directory
 export const CLI_ROOT = resolve(__dirname, '../..');
 
+// Embedded templates directory (inside CLI package)
+export const TEMPLATES_DIR = join(CLI_ROOT, 'templates');
+
 // Target folder mappings
 export const TARGETS = {
   claude: '.claude',
@@ -16,6 +19,22 @@ export const TARGETS = {
   generic: '.agent'
 };
 
+/**
+ * Get embedded templates (bundled with CLI)
+ */
+export function getEmbeddedTemplates() {
+  if (existsSync(TEMPLATES_DIR)) {
+    const agentsMd = join(TEMPLATES_DIR, 'AGENTS.md');
+    return {
+      path: TEMPLATES_DIR,
+      type: 'embedded',
+      claudeDir: TEMPLATES_DIR,
+      agentsMd: existsSync(agentsMd) ? agentsMd : null
+    };
+  }
+  return null;
+}
+
 /**
  * Find source directory by traversing up from cwd
  * Algorithm: cwd → parent → git root
@@ -122,9 +141,11 @@ export function getTargetDir(projectDir, target = 'claude') {
 }
 
 /**
- * Resolve source path (from --source flag or auto-detect)
+ * Resolve source path (from --source flag, embedded templates, or auto-detect)
+ * Priority: 1. --source flag  2. Embedded templates  3. Auto-detect in parent dirs
  */
 export function resolveSource(sourceFlag) {
+  // 1. If --source flag provided, use it
   if (sourceFlag) {
     const resolved = resolve(sourceFlag);
     if (!existsSync(resolved)) {
@@ -138,6 +159,7 @@ export function resolveSource(sourceFlag) {
     if (existsSync(claudeDir)) {
       return {
         path: resolved,
+        type: 'custom',
         claudeDir,
         agentsMd: existsSync(join(resolved, 'AGENTS.md')) ? join(resolved, 'AGENTS.md') : null
       };
@@ -146,6 +168,7 @@ export function resolveSource(sourceFlag) {
     if (existsSync(opencodeDir)) {
       return {
         path: resolved,
+        type: 'custom',
         claudeDir: opencodeDir,
         agentsMd: existsSync(join(resolved, 'AGENTS.md')) ? join(resolved, 'AGENTS.md') : null
       };
@@ -154,13 +177,19 @@ export function resolveSource(sourceFlag) {
     return { error: `No .claude/ or .opencode/ found in: ${sourceFlag}` };
   }
 
-  // Auto-detect
+  // 2. Use embedded templates (bundled with CLI) - PREFERRED
+  const embedded = getEmbeddedTemplates();
+  if (embedded) {
+    return embedded;
+  }
+
+  // 3. Fallback: auto-detect in parent directories
   const found = findSource();
-  if (!found) {
-    return {
-      error: 'Could not find source. Use --source flag or ensure AGENTS.md/.claude/ exists in parent directories.'
-    };
+  if (found) {
+    return found;
   }
 
-  return found;
+  return {
+    error: 'No templates found. The CLI package may be corrupted. Try reinstalling: npm install -g apero-kit-cli'
+  };
 }

package/templates/AGENTS.md

@@ -0,0 +1,104 @@
+# AGENTS.md - Working Conventions
+
+---
+
+## 1) Language
+- **Repository artifacts (mandatory)**: All documentation/guides, code comments, and any text written into files must be in **English**.
+- **Conversation**: Replies in the chat should be in **Vietnamese**.
+
+---
+
+## 2) Core Principles (Non-negotiable)
+- Clarify Ambiguity First: If a requirement is unclear or incomplete, ask 1-2 clarifying questions before proceeding. Never guess.
+- Code Only What Was Asked: Follow the PRD/ticket scope strictly; no extra features.
+- Minimum Viable Change: Deliver the simplest, most idempotent fix that works; avoid over-engineering.
+- Reuse Before Rewriting: Prefer existing modules or utilities; avoid duplication.
+- File Length Limit: Keep every file under 300 LOC; if a change would exceed this, pause and propose a refactor or split plan.
+- Configuration and Secrets: Load all secrets or config from environment variables only; never hardcode.
+- When writing code, aim for simplicity and readability, not just brevity. Short code that is hard to read is worse than slightly longer code that is clear.
+- Clean Up Temporary Files: Delete any temporary test files immediately after use.
+
+### Core Directives
+- WRITE CODE ONLY TO SPEC.
+- MINIMUM, NOT MAXIMUM.
+- ONE SIMPLE SOLUTION.
+- CLARIFY, DON'T ASSUME.
+
+### Philosophy (Non-negotiables)
+- Do not add unnecessary files or modules; if a new file is unavoidable, justify it.
+- Do not change architecture or patterns unless explicitly required and justified.
+- Prioritize readability and maintainability over clever or complex code.
+
+---
+
+## 3) File-reading Rules (Mandatory)
+- **Before editing/creating files**: Read all relevant files in full to understand context.
+- **Before starting a task**: Read at minimum `README.md` and relevant files in `docs/*` (if present).
+- **If docs are missing or likely stale**: Use `rg` to locate the source of truth quickly.
+
+---
+
+## 4) Project Structure Index
+
+> **File**: `docs/structure.md` - Single source of truth for project layout.
+
+### When to use `docs/structure.md`
+- **Hard-to-locate tasks** (large repo/monorepo): read it first to get the map and narrow the search area.
+- **Very broad keywords** (e.g., auth/payment/logging): use structure to pick the right folder before searching deeper.
+- **New project / onboarding**: structure gives a fast overview of the main areas.
+
+### When to use `rg`
+- **Normal tasks**: use `rg` directly to find the real implementation (does not depend on whether structure is up to date).
+- **You already have concrete identifiers** (file name / function / class / route / endpoint): `rg` is faster than structure.
+- **You suspect structure is stale**: prefer `rg` first, then refresh structure if needed.
+
+### When to Update
+- **Project has no `docs/structure.md`**: Generate it using `skills/project-index/SKILL.md`.
+- **After major changes**: Added/removed modules, restructured folders.
+- **Periodic refresh**: Weekly or when index feels outdated.
+- **User says**: "update structure", "refresh index", "scan project".
+
+### How to Generate/Update
+```
+Load: skills/project-index/SKILL.md
+- Scan project tree
+- Identify key files and patterns
+- Write to docs/structure.md
+```
+
+---
+
+## 5) Dynamic Context Loading
+
+> **Golden Rule**: Only load context when matching triggers are detected.
+
+### Automatic Context Triggers
+- **Keywords**: If the request matches a domain (e.g., "debug", "test", "plan", "review"), ALWAYS load the corresponding **Skill** (`skills/**/SKILL.md`) or **Agent** (`agents/**`) first.
+- **Slash Commands**: Treat `/command` as an explicit instruction to load `commands/<command>.md` (e.g., `/fix`, `/plan`, `/test`).
+- **Complex Tasks**: For multi-step objectives, load `workflows/**` to orchestrate the process.
+
+### Hierarchy of Context
+1. **Workflows** (`workflows/**`): High-level orchestration for multi-step processes.
+2. **Agents** (`agents/**`): Specific personas/mindsets for a task type.
+3. **Skills** (`skills/**`): Domain-specific knowledge and playbooks.
+4. **Commands** (`commands/**`): Reusable execution scripts/procedures.
+
+### Discovery
+If a request is unclear, check `router/decision-flow.md` or scan `skills/` and `commands/` directories to find the best tool for the job. Never guess if a specialized tool exists.
+
+---
+
+## 6) Execution Discipline
+- **Run only necessary commands**; avoid destructive commands (`rm`, `git reset`...) unless explicitly requested.
+- **Timeout**: Default 60s; cap at 70-80s for potentially long-running commands.
+- **Permission errors**: Explain clearly and propose safe manual steps.
+- **New dependencies**: Do not add unless truly necessary and user agrees.
+
+---
+
+## 7) Auto-Documentation
+After completing impactful changes (feature/bugfix/schema/architecture), update briefly:
+- `README.md`: If stable info (stack/versions/overview) affected.
+- `HANDOFF.md`: Current status + next steps + latest test results.
+- `CHANGELOG.md`: Add one line: `YYYY-MM-DD: <Fix|Add|Change|Remove> <what> at <path> - <impact> (completed).`
+- `docs/structure.md`: If added/removed files or restructured folders.

package/templates/README.md

@@ -0,0 +1,241 @@
+# 🏠 .claude - AI Control Center
+
+## What is .claude?
+
+The **`.claude`** directory is the "extended brain" of the AI - containing all configurations, knowledge, and processes that enable the AI to work smarter and more professionally.
+
+**Simple Example:**
+- Without `.claude`: The AI responds like a standard chatbot.
+- With `.claude`: The AI operates as a full team of specialized experts.
+
+---
+
+## Overview Structure
+
+```
+.claude/
+│
+├── 🤖 agents/          ← ROLES (Who does it?)
+│   └── 17 distinct expert personas
+│
+├── 📋 commands/        ← PROCEDURES (How is it done?)
+│   └── 50+ standardized workflows
+│
+├── 📚 skills/          ← KNOWLEDGE (What to know?)
+│   └── 59 domain-specific knowledge bases
+│
+├── 🧭 router/          ← ROUTING (What to choose?)
+│   └── 5 decision-making guides
+│
+├── 🔄 workflows/       ← ORCHESTRATION (Big tasks)
+│   └── 4 collaboration scenarios
+│
+├── ⚡ hooks/           ← AUTOMATION (Trigger events)
+│   └── 15+ automated scripts
+│
+├── 🔧 scripts/         ← UTILITIES (Tools)
+│   └── 10+ helper scripts
+│
+└── ⚙️ settings.json    ← CONFIG (Customization)
+```
+
+---
+
+## Directory Explanation
+
+### 🤖 agents/ - Expert Roles
+
+**What it is:** 17 different "personas" the AI can embody.
+
+**Examples:**
+| You say | AI embodies |
+|---------|-------------|
+| "Fix bug" | Debugger (Bug Hunter) |
+| "Write code" | Developer (Programmer) |
+| "Make a plan" | Planner (Architect) |
+
+📖 [See details in agents/README.md](agents/README.md)
+
+---
+
+### 📋 commands/ - Workflows
+
+**What it is:** 50+ step-by-step "recipes" for specific tasks.
+
+**Examples:**
+| Command | Action |
+|---------|--------|
+| `/fix` | Standard 5-step bug fix |
+| `/code` | Coding workflow with testing |
+| `/plan` | Planning template |
+
+📖 [See details in commands/README.md](commands/README.md)
+
+---
+
+### 📚 skills/ - Specialized Knowledge
+
+**What it is:** 59 knowledge packages loaded on demand.
+
+**Examples:**
+| Skill | Contains |
+|-------|----------|
+| `ui-ux-pro-max` | 50 styles, 21 palettes, 50 fonts |
+| `debugging` | 4-step debug framework |
+| `better-auth` | OAuth, 2FA guides |
+
+📖 [See details in skills/README.md](skills/README.md)
+
+---
+
+### 🧭 router/ - Decision Engine
+
+**What it is:** The "decision brain" - helps AI select the right agent/command/skill.
+
+**How it works:**
+```
+You: "Fix login error"
+        ↓
+Router analyzes keywords
+        ↓
+Selects: Debugger + /fix + better-auth
+        ↓
+AI starts working
+```
+
+📖 [See details in router/README.md](router/README.md)
+
+---
+
+### 🔄 workflows/ - Multi-step Collaboration
+
+**What it is:** Scripts for large tasks requiring coordination.
+
+**Example:** New Feature
+```
+Planner → Developer → Tester → Reviewer → Docs Manager
+```
+
+📖 [See details in workflows/README.md](workflows/README.md)
+
+---
+
+### ⚡ hooks/ - Automation
+
+**What it is:** Code that runs automatically on events.
+
+**Examples:**
+| Event | Hook runs |
+|-------|-----------|
+| File edit | Auto-format (Prettier) |
+| Task done | Auto-review |
+| Session start | Auto-load context |
+
+📖 [See details in hooks/README.md](hooks/README.md)
+
+---
+
+### 🔧 scripts/ - Utility Tools
+
+**What it is:** Helper scripts.
+
+**Examples:**
+| Script | Action |
+|--------|--------|
+| `scan_skills.py` | Scans and generates skills list |
+| `worktree.cjs` | Manages git worktrees |
+| `ck-help.py` | Command lookup |
+
+📖 [See details in scripts/README.md](scripts/README.md)
+
+---
+
+## How It All Works Together
+
+### Example: "Add dark mode to app"
+
+```
+STEP 1: Router Analysis
+├── Keywords: "add", "dark mode"
+├── Task Type: New Feature
+└── Complexity: Medium
+
+STEP 2: Resource Selection
+├── Agents: planner → developer → tester
+├── Commands: /plan → /code → /test
+├── Skills: ui-ux-pro-max, frontend-development
+└── Workflow: primary-workflow
+
+STEP 3: Execution
+├── Planner creates plan
+├── Developer writes code
+├── Tester writes tests
+└── Hooks auto-format & review
+
+STEP 4: Completion
+├── Code merged
+├── Docs updated (automated)
+└── Changelog recorded (automated)
+```
+
+---
+
+## Quick Reference
+
+| Need | Look in |
+|------|---------|
+| Who does the work | `agents/` |
+| What process to follow | `commands/` |
+| What knowledge is needed | `skills/` |
+| How AI decides | `router/` |
+| Large multi-step tasks | `workflows/` |
+| Automation | `hooks/` |
+| Utility tools | `scripts/` |
+
+---
+
+## Configuration Files
+
+| File | Function |
+|------|----------|
+| `settings.json` | General config |
+| `.env` | Environment variables (do not commit) |
+| `.env.example` | Env var template |
+| `.mcp.json.example` | MCP server config |
+| `.gitignore` | Ignored files |
+
+---
+
+## Summary
+
+| Directory | Count | Function |
+|-----------|-------|----------|
+| agents | 17 | Expert Roles |
+| commands | 50+ | Workflows |
+| skills | 59 | Specialized Knowledge |
+| router | 5 | Decision Routing |
+| workflows | 4 | Orchestration |
+| hooks | 15+ | Automation |
+| scripts | 10+ | Utilities |
+
+---
+
+## Where to Start?
+
+### If you are new:
+1. Read [agents/README.md](agents/README.md) - Understand roles
+2. Read [commands/README.md](commands/README.md) - Understand workflows
+3. Try simple requests
+
+### If you want to customize:
+1. See [skills/README.md](skills/README.md) - Create custom skills
+2. See [hooks/README.md](hooks/README.md) - Add automation
+3. See [router/README.md](router/README.md) - Understand decision logic
+
+---
+
+## Quick Links
+
+- [📖 AGENTS.md](../AGENTS.md) - Core Ruleset
+- [📖 README.md](../README.md) - Project Overview
+- [🔧 Settings](settings.json) - Configuration

package/templates/agents/README.md

@@ -0,0 +1,172 @@
+# 🤖 Agents - Các Vai Trò Chuyên Gia
+
+## Agents là gì?
+
+**Agents** giống như các "nhân cách chuyên gia" khác nhau mà AI sẽ nhập vai để làm việc. Mỗi agent có cách suy nghĩ, phương pháp làm việc và chuyên môn riêng.
+
+**Ví dụ đơn giản:**
+- Khi bạn nhờ **sửa bug** → AI sẽ nhập vai **Debugger** (thợ săn lỗi)
+- Khi bạn nhờ **viết code** → AI sẽ nhập vai **Developer** (lập trình viên)
+- Khi bạn nhờ **lập kế hoạch** → AI sẽ nhập vai **Planner** (kiến trúc sư)
+
+---
+
+## Danh Sách 17 Agents
+
+### 👨‍💻 Nhóm Lập Trình
+
+| Agent | Vai Trò | Khi Nào Được Gọi | Công Việc Chính |
+|-------|---------|------------------|-----------------|
+| **fullstack-developer** | Lập trình viên | Bạn nói: "code", "viết", "tạo", "thêm tính năng" | Viết code, tạo components, xây dựng tính năng |
+| **code-reviewer** | Người kiểm tra code | Bạn nói: "review", "kiểm tra code", "refactor" | Đánh giá chất lượng code, đề xuất cải thiện |
+| **tester** | Người viết test | Bạn nói: "test", "kiểm thử", "coverage" | Viết test tự động, đảm bảo code chạy đúng |
+
+### 🔧 Nhóm Sửa Lỗi & Tìm Kiếm
+
+| Agent | Vai Trò | Khi Nào Được Gọi | Công Việc Chính |
+|-------|---------|------------------|-----------------|
+| **debugger** | Thợ săn lỗi | Bạn nói: "bug", "lỗi", "crash", "không chạy" | Tìm nguyên nhân lỗi, phân tích log, sửa bugs |
+| **scout** | Thám tử nội bộ | Bạn nói: "tìm", "ở đâu", "file nào" | Tìm kiếm trong code, định vị files và functions |
+| **scout-external** | Thám tử bên ngoài | Bạn nói: "tìm docs", "thư viện nào", "API" | Tìm tài liệu, API docs, thư viện bên ngoài |
+
+### 📋 Nhóm Lập Kế Hoạch & Quản Lý
+
+| Agent | Vai Trò | Khi Nào Được Gọi | Công Việc Chính |
+|-------|---------|------------------|-----------------|
+| **planner** | Kiến trúc sư | Bạn nói: "kế hoạch", "thiết kế", "architecture" | Lập kế hoạch, thiết kế hệ thống |
+| **project-manager** | Quản lý dự án | Bạn nói: "tiến độ", "deadline", "task" | Theo dõi công việc, quản lý tiến độ |
+| **researcher** | Nhà nghiên cứu | Bạn nói: "nghiên cứu", "tìm hiểu", "so sánh" | Nghiên cứu công nghệ, phân tích giải pháp |
+
+### 🎨 Nhóm Thiết Kế & Nội Dung
+
+| Agent | Vai Trò | Khi Nào Được Gọi | Công Việc Chính |
+|-------|---------|------------------|-----------------|
+| **ui-ux-designer** | Thiết kế giao diện | Bạn nói: "UI", "giao diện", "layout", "đẹp" | Thiết kế màn hình, cải thiện trải nghiệm |
+| **copywriter** | Viết nội dung | Bạn nói: "viết content", "marketing" | Viết văn bản, nội dung marketing |
+| **brainstormer** | Sáng tạo ý tưởng | Bạn nói: "ý tưởng", "gợi ý", "brainstorm" | Đưa ra ý tưởng, đề xuất giải pháp sáng tạo |
+
+### 🛠️ Nhóm Hỗ Trợ Kỹ Thuật
+
+| Agent | Vai Trò | Khi Nào Được Gọi | Công Việc Chính |
+|-------|---------|------------------|-----------------|
+| **git-manager** | Chuyên gia Git | Bạn nói: "commit", "merge", "branch", "PR" | Quản lý phiên bản code, xử lý xung đột |
+| **database-admin** | Quản trị cơ sở dữ liệu | Bạn nói: "database", "SQL", "migration" | Thiết kế database, viết queries |
+| **docs-manager** | Viết tài liệu | Bạn nói: "docs", "README", "hướng dẫn" | Viết và cập nhật tài liệu |
+| **mcp-manager** | Chuyên gia MCP | Bạn nói: "MCP", "tool", "tích hợp" | Quản lý công cụ MCP |
+| **journal-writer** | Ghi chép công việc | Bạn nói: "ghi lại", "journal", "log" | Ghi chép tiến độ làm việc |
+
+---
+
+## Cách AI Chọn Agent
+
+### Bước 1: Bạn đưa ra yêu cầu
+```
+"Sửa lỗi đăng nhập không được"
+```
+
+### Bước 2: AI nhận diện từ khóa
+```
+Từ khóa "sửa lỗi" → Cần vai trò Debugger (thợ săn lỗi)
+```
+
+### Bước 3: AI nhập vai chuyên gia
+```
+AI đọc file: agents/debugger.md
+→ Học cách suy nghĩ như thợ săn lỗi chuyên nghiệp
+```
+
+### Bước 4: AI làm việc theo phong cách chuyên gia
+```
+Debugger sẽ:
+1. Hỏi: "Lỗi hiện như thế nào? Có thông báo gì không?"
+2. Phân tích log để tìm manh mối
+3. Tìm ra nguyên nhân gốc rễ (không chỉ sửa triệu chứng)
+4. Đề xuất cách sửa và kiểm tra lại
+```
+
+---
+
+## Ví Dụ Thực Tế
+
+### Ví dụ 1: Việc đơn giản (1 agent)
+
+**Bạn hỏi:** "Tìm hàm xử lý thanh toán trong dự án"
+
+**AI chọn:** `scout` (thám tử)
+
+**Vì sao:** Từ "tìm" → cần người chuyên tìm kiếm
+
+---
+
+### Ví dụ 2: Việc phức tạp (nhiều agents phối hợp)
+
+**Bạn hỏi:** "Thêm tính năng dark mode cho app"
+
+**AI chọn theo thứ tự:**
+
+| Thứ tự | Agent | Làm gì |
+|--------|-------|--------|
+| 1 | **planner** | Lập kế hoạch: cần sửa gì, thêm gì |
+| 2 | **ui-ux-designer** | Chọn màu sắc cho dark mode |
+| 3 | **fullstack-developer** | Viết code thực hiện |
+| 4 | **tester** | Viết test kiểm tra |
+| 5 | **docs-manager** | Cập nhật hướng dẫn sử dụng |
+
+---
+
+## Tại Sao Cần Agents?
+
+| ❌ Không có Agents | ✅ Có Agents |
+|-------------------|--------------|
+| AI trả lời chung chung | AI trả lời như chuyên gia thực thụ |
+| Không có quy trình rõ ràng | Làm việc theo quy trình chuyên nghiệp |
+| Dễ bỏ sót bước quan trọng | Đảm bảo đầy đủ các bước cần thiết |
+| Thiếu chiều sâu chuyên môn | Có kiến thức chuyên sâu từng lĩnh vực |
+
+---
+
+## Mỗi File Agent Chứa Gì?
+
+Ví dụ file `debugger.md`:
+
+```markdown
+# Debugger - Thợ Săn Lỗi
+
+## Vai trò
+Chuyên tìm và sửa lỗi trong code
+
+## Cách suy nghĩ
+- Luôn tìm nguyên nhân gốc rễ, không chỉ sửa triệu chứng
+- Phân tích log và stack trace cẩn thận
+- Đặt câu hỏi "Tại sao?" liên tục
+
+## Quy trình làm việc
+1. Thu thập thông tin về lỗi
+2. Tái tạo lỗi
+3. Phân tích nguyên nhân
+4. Sửa lỗi
+5. Kiểm tra lại
+
+## Công cụ thường dùng
+- Đọc log: get_errors, run_in_terminal
+- Tìm code: grep_search, read_file
+```
+
+---
+
+## Tóm Tắt
+
+| Khái niệm | Giải thích |
+|-----------|------------|
+| **Agent là gì** | Vai trò chuyên gia mà AI sẽ nhập vai |
+| **Có bao nhiêu** | 17 agents cho 17 loại công việc |
+| **Ai chọn agent** | AI tự động chọn dựa trên từ khóa bạn dùng |
+| **Khi nào dùng nhiều agents** | Khi công việc phức tạp cần nhiều chuyên môn |
+
+---
+
+## Xem Thêm
+
+- [Danh sách Commands (Quy trình)](../commands/README.md) - Các bước thực hiện công việc
+- [Danh sách Skills (Kiến thức)](../skills/README.md) - Kiến thức chuyên môn
+- [Router (Bộ định tuyến)](../router/README.md) - Cách AI quyết định