apero-kit-cli 1.0.0 → 1.2.0

package/templates/commands/skill/plan.md

@@ -0,0 +1,45 @@
+---
+description: Plan to create a new agent skill
+argument-hint: [skill-name] [prompt]
+---
+
+Think harder.
+First: Activate `skill-creator` and `claude-code` skills.
+Use `docs-seeker` skills to search for documentation if needed.
+Employ `sequential-thinking` or `problem-solving` skills for complex problem-solving that requires structured analysis
+Finally, when creating a plan, activate `planning` skill.
+
+## Arguments
+SKILL: $1 (default: `*`)
+PROMPT: $2 (default: empty)
+
+## Your mission
+Propose a plan to create a new skill in `.claude/skills/${SKILL}` directory. 
+When you finish, ask user to review your plan:
+- If the user approve: Write down a plan follow "Output Requirements", then ask user if they want to start implementing.
+- If the user reject: Revise the plan or ask more questions to clarify more about the user's request (ask one question at the time), then repeat the review process.
+
+## Additional instructions
+<additional-instructions>$PROMPT</additional-instructions>
+
+## Your Approach
+1. **Question Everything**: Ask probing questions to fully understand the user's request, constraints, and true objectives. Don't assume - clarify until you're 100% certain.
+2. **Brutal Honesty**: Provide frank, unfiltered feedback about ideas. If something is unrealistic, over-engineered, or likely to cause problems, say so directly. Your job is to prevent costly mistakes.
+3. **Explore Alternatives**: Always consider multiple approaches. Present 2-3 viable solutions with clear pros/cons, explaining why one might be superior.
+4. **Challenge Assumptions**: Question the user's initial approach. Often the best solution is different from what was originally envisioned.
+5. **Consider All Stakeholders**: Evaluate impact on end users, developers, operations team, and business objectives.
+
+## Output Requirements
+An output implementation plan must also follow the progressive disclosure structure:
+- Always keep in mind that `SKILL.md` and reference files should be token consumption efficient, so that **progressive disclosure** can be leveraged at best.
+- `SKILL.md` is always short and concise, straight to the point, treat it as a quick reference guide.
+- Create a directory using naming pattern from `## Naming` section.
+- Save the overview access point at `plan.md`, keep it generic, under 80 lines, and list each phase with status/progress and links.
+- For each phase, add `phase-XX-phase-name.md` files containing sections (Context links, Overview with date/priority/statuses, Key Insights, Requirements, Architecture, Related code files, Implementation Steps, Todo list, Success Criteria, Risk Assessment, Security Considerations, Next steps).
+
+**IMPORTANT:**
+- Analyze the given task and use `AskUserQuestion` tool to ask for more details if needed.
+- Ensure token consumption efficiency while maintaining high quality.
+- Skills are not documentation, they are practical instructions for Claude Code to use the tools, packages, plugins or APIs to achieve the tasks.
+- Each skill teaches Claude how to perform a specific development task, not what a tool does.
+- Claude Code can activate multiple skills automatically to achieve the user's request.

package/templates/commands/test/ui.md

@@ -0,0 +1,92 @@
+---
+description: ⚡⚡ Run UI tests on a website & generate a detailed report.
+argument-hint: [url] [options]
+---
+
+Activate the chrome-devtools skill.
+
+## Purpose
+Run comprehensive UI tests on a website and generate a detailed report.
+
+## Arguments
+- $1: URL - The URL of the website to test
+- $2: OPTIONS - Optional test configuration (e.g., --headless, --mobile, --auth)
+
+## Testing Protected Routes (Authentication)
+
+For testing protected routes that require authentication, follow this workflow:
+
+### Step 1: User Manual Login
+Instruct the user to:
+1. Open the target site in their browser
+2. Log in manually with their credentials
+3. Open browser DevTools (F12) → Application tab → Cookies/Storage
+
+### Step 2: Extract Auth Credentials
+Ask the user to provide one of:
+- **Cookies**: Copy cookie values (name, value, domain)
+- **Access Token**: Copy JWT/Bearer token from localStorage or cookies
+- **Session Storage**: Copy relevant session keys
+
+### Step 3: Inject Authentication
+Use the `inject-auth.js` script to inject credentials before testing:
+
+```bash
+cd $SKILL_DIR  # .claude/skills/chrome-devtools/scripts
+
+# Option A: Inject cookies
+node inject-auth.js --url https://example.com --cookies '[{"name":"session","value":"abc123","domain":".example.com"}]'
+
+# Option B: Inject Bearer token
+node inject-auth.js --url https://example.com --token "Bearer eyJhbGciOi..." --header Authorization --token-key access_token
+
+# Option C: Inject localStorage
+node inject-auth.js --url https://example.com --local-storage '{"auth_token":"xyz","user_id":"123"}'
+
+# Combined (cookies + localStorage)
+node inject-auth.js --url https://example.com --cookies '[{"name":"session","value":"abc"}]' --local-storage '{"user":"data"}'
+```
+
+### Step 4: Run Tests
+After auth injection, the browser session persists. Run tests normally:
+
+```bash
+# Navigate and screenshot protected pages
+node navigate.js --url https://example.com/dashboard
+node screenshot.js --url https://example.com/profile --output profile.png
+
+# The auth session persists until --close true is used
+node screenshot.js --url https://example.com/settings --output settings.png --close true
+```
+
+### Auth Script Options
+- `--cookies '<json>'` - Inject cookies (JSON array)
+- `--token '<token>'` - Inject Bearer token
+- `--token-key '<key>'` - localStorage key for token (default: access_token)
+- `--header '<name>'` - Set HTTP header with token (e.g., Authorization)
+- `--local-storage '<json>'` - Inject localStorage items
+- `--session-storage '<json>'` - Inject sessionStorage items
+- `--reload true` - Reload page after injection
+- `--clear true` - Clear saved auth session
+
+## Workflow
+- Use `planning` skill to organize the test plan & report in the current project directory.
+- All the screenshots should be saved in the same report directory.
+- Browse $URL with the specified $OPTIONS, discover all pages, components, and endpoints.
+- Create a test plan based on the discovered structure
+- Use multiple `tester` subagents or tool calls in parallel to test all pages, forms, navigation, user flows, accessibility, functionalities, usability, responsive layouts, cross-browser compatibility, performance, security, seo, etc.
+- Use `ai-multimodal` to analyze all screenshots and visual elements.
+- Generate a comprehensive report in Markdown format, embedding all screenshots directly in the report.
+- Finally respond to the user with a concise summary of findings and recommendations.
+- Use `AskUserQuestion` tool to ask if user wants to preview the report with `/preview` slash command.
+
+## Output Requirements
+How to write reports:
+- Format: Use clear, structured Markdown with headers, lists, and code blocks where appropriate
+- Include the test results summary, key findings, and screenshot references
+- **IMPORTANT:** Ensure token efficiency while maintaining high quality.
+- **IMPORTANT:** Sacrifice grammar for the sake of concision when writing reports.
+- **IMPORTANT:** In reports, list any unresolved questions at the end, if any.
+
+**IMPORTANT**: **Do not** start implementing the fixes.
+**IMPORTANT:** Analyze the skills catalog and activate the skills that are needed for the task during the process.

package/templates/commands/test.md

@@ -0,0 +1,8 @@
+---
+description: ⚡ Run tests locally and analyze the summary report.
+---
+
+Use the `tester` subagent to run tests locally and analyze the summary report.
+
+**IMPORTANT**: **Do not** start implementing.
+**IMPORTANT:** Analyze the skills catalog and activate the skills that are needed for the task during the process.

package/templates/commands/use-mcp.md

@@ -0,0 +1,34 @@
+---
+description: Utilize tools of Model Context Protocol (MCP) servers
+argument-hint: [task]
+---
+Execute MCP operations via **Gemini CLI** to preserve context budget.
+
+## Execution Steps
+
+1. **Execute task via Gemini CLI** (using stdin pipe for MCP support):
+   ```bash
+   # IMPORTANT: Use stdin piping, NOT -p flag (deprecated, skips MCP init)
+   echo "$ARGUMENTS. Return JSON only per GEMINI.md instructions." | gemini -y -m gemini-2.5-flash
+   ```
+
+2. **Fallback to mcp-manager subagent** (if Gemini CLI unavailable):
+   - Use `mcp-manager` subagent to discover and execute tools
+   - If the subagent got issues with the scripts of `mcp-management` skill, use `mcp-builder` skill to fix them
+   - **DO NOT** create ANY new scripts
+   - The subagent can only use MCP tools if any to achieve this task
+   - If the subagent can't find any suitable tools, just report it back to the main agent to move on to the next step
+
+## Important Notes
+
+- **MUST use stdin piping** - the deprecated `-p` flag skips MCP initialization
+- Use `-y` flag to auto-approve tool execution
+- **GEMINI.md auto-loaded**: Gemini CLI automatically loads `GEMINI.md` from project root, enforcing JSON-only response format
+- **Parseable output**: Responses are structured JSON: `{"server":"name","tool":"name","success":true,"result":<data>,"error":null}`
+
+## Anti-Pattern (DO NOT USE)
+
+```bash
+# BROKEN - deprecated -p flag skips MCP server connections!
+gemini -y -m gemini-2.5-flash -p "..."
+```

package/templates/commands/watzup.md

@@ -0,0 +1,8 @@
+---
+description: ⚡ Review recent changes and wrap up the work
+---
+Review my current branch and the most recent commits. 
+Provide a detailed summary of all changes, including what was modified, added, or removed. 
+Analyze the overall impact and quality of the changes.
+
+**IMPORTANT**: **Do not** start implementing.

package/templates/commands/worktree.md

@@ -0,0 +1,126 @@
+---
+description: Create isolated git worktree for parallel development
+argument-hint: [feature-description] OR [project] [feature] (monorepo)
+---
+
+Create an isolated git worktree for parallel feature development.
+
+## Workflow
+
+### Step 1: Get Repository Info
+
+```bash
+node .claude/scripts/worktree.cjs info --json
+```
+
+**Response fields:**
+- `repoType`: "monorepo" or "standalone"
+- `baseBranch`: detected base branch
+- `projects`: array of {name, path} for monorepo
+- `envFiles`: array of .env* files found
+- `dirtyState`: boolean
+
+### Step 2: Gather Info via AskUserQuestion
+
+**Detect branch prefix from user's description:**
+- Keywords "fix", "bug", "error", "issue" → prefix = `fix`
+- Keywords "refactor", "restructure", "rewrite" → prefix = `refactor`
+- Keywords "docs", "documentation", "readme" → prefix = `docs`
+- Keywords "test", "spec", "coverage" → prefix = `test`
+- Keywords "chore", "cleanup", "deps" → prefix = `chore`
+- Keywords "perf", "performance", "optimize" → prefix = `perf`
+- Everything else → prefix = `feat`
+
+**For MONOREPO:** Use AskUserQuestion if project not specified:
+```javascript
+// If user said "/worktree add auth" but multiple projects exist
+AskUserQuestion({
+  questions: [{
+    header: "Project",
+    question: "Which project should the worktree be created for?",
+    options: projects.map(p => ({ label: p.name, description: p.path })),
+    multiSelect: false
+  }]
+})
+```
+
+**For env files:** Always ask which to copy:
+```javascript
+AskUserQuestion({
+  questions: [{
+    header: "Env files",
+    question: "Which environment files should be copied to the worktree?",
+    options: envFiles.map(f => ({ label: f, description: "Copy to worktree" })),
+    multiSelect: true
+  }]
+})
+```
+
+### Step 3: Convert Description to Slug
+
+- "add authentication system" → `add-auth`
+- "fix login bug" → `login-bug`
+- Remove filler words, kebab-case, max 50 chars
+
+### Step 4: Execute Command
+
+**Monorepo:**
+```bash
+node .claude/scripts/worktree.cjs create "<PROJECT>" "<SLUG>" --prefix <TYPE> --env "<FILES>"
+```
+
+**Standalone:**
+```bash
+node .claude/scripts/worktree.cjs create "<SLUG>" --prefix <TYPE> --env "<FILES>"
+```
+
+**Options:**
+- `--prefix` - Branch type: feat|fix|refactor|docs|test|chore|perf
+- `--env` - Comma-separated .env files to copy
+- `--json` - Output JSON for parsing
+- `--dry-run` - Preview without executing
+
+## Commands
+
+| Command | Usage | Description |
+|---------|-------|-------------|
+| `create` | `create [project] <feature>` | Create new worktree |
+| `remove` | `remove <name-or-path>` | Remove worktree and branch |
+| `info` | `info` | Get repo info |
+| `list` | `list` | List existing worktrees |
+
+## Error Codes
+
+| Code | Meaning | Action |
+|------|---------|--------|
+| `MISSING_ARGS` | Missing project/feature for monorepo | Ask for both |
+| `MISSING_FEATURE` | No feature name (standalone) | Ask for feature |
+| `PROJECT_NOT_FOUND` | Project not in .gitmodules | Show available projects |
+| `MULTIPLE_PROJECTS_MATCH` | Ambiguous project name | Use AskUserQuestion |
+| `MULTIPLE_WORKTREES_MATCH` | Ambiguous worktree for remove | Use AskUserQuestion |
+| `BRANCH_CHECKED_OUT` | Branch in use elsewhere | Suggest different name |
+| `WORKTREE_EXISTS` | Path already exists | Suggest use or remove |
+| `WORKTREE_CREATE_FAILED` | Git command failed | Show git error |
+| `WORKTREE_REMOVE_FAILED` | Cannot remove worktree | Check uncommitted changes |
+
+## Example Session
+
+```
+User: /worktree fix the login validation bug
+
+Claude: [Runs: node .claude/scripts/worktree.cjs info --json]
+        [Detects: standalone repo, envFiles: [".env.example"]]
+        [Detects prefix from "fix" keyword: fix]
+        [Converts slug: "login-validation-bug"]
+
+Claude: [Uses AskUserQuestion for env files]
+        "Which environment files should be copied?"
+        Options: .env.example
+
+User: .env.example
+
+Claude: [Runs: node .claude/scripts/worktree.cjs create "login-validation-bug" --prefix fix --env ".env.example"]
+
+Output: Worktree created at ../worktrees/myrepo-login-validation-bug
+        Branch: fix/login-validation-bug
+```

package/templates/hooks/.python-cache.json

@@ -0,0 +1 @@
+{"version":"Python 3.12.10","timestamp":1767230959174}

package/templates/hooks/README.md

@@ -0,0 +1,246 @@
+# ⚡ Hooks - Tự Động Hóa Theo Sự Kiện
+
+## Hooks là gì?
+
+**Hooks** là các "trigger tự động" - code sẽ tự chạy khi có sự kiện nhất định xảy ra. Giống như cài báo thức vậy - đến giờ thì tự động reo, không cần bạn bấm gì.
+
+**Ví dụ đơn giản:**
+- Khi **bắt đầu session** → Tự động chào và kiểm tra trạng thái dự án
+- Khi **sửa file** → Tự động format code (Prettier)
+- Khi **hoàn thành task** → Tự động review lại code
+- Khi **kết thúc session** → Tự động ghi log công việc
+
+---
+
+## Danh Sách Hooks
+
+### 🟢 Hooks Khởi Động
+
+| Hook | Chạy Khi Nào | Làm Gì |
+|------|--------------|--------|
+| **session-init.cjs** | Bắt đầu session mới | Load context, kiểm tra dự án |
+| **subagent-init.cjs** | Khởi tạo subagent | Chuẩn bị context cho subagent |
+
+### 📝 Hooks Khi Sửa File
+
+| Hook | Chạy Khi Nào | Làm Gì |
+|------|--------------|--------|
+| **post-edit-prettier.cjs** | Sau khi sửa file | Format code bằng Prettier |
+| **write-compact-marker.cjs** | Khi ghi file | Đánh dấu compact writes |
+
+### 🔍 Hooks Review & Kiểm Tra
+
+| Hook | Chạy Khi Nào | Làm Gì |
+|------|--------------|--------|
+| **post-task-review.cjs** | Sau khi hoàn thành task | Tự động review code |
+| **workflow-router.cjs** | Khi cần chọn workflow | Định tuyến đến workflow phù hợp |
+| **dev-rules-reminder.cjs** | Khi code | Nhắc nhở quy tắc phát triển |
+
+### 🔒 Hooks Bảo Mật
+
+| Hook | Chạy Khi Nào | Làm Gì |
+|------|--------------|--------|
+| **privacy-block.cjs** | Khi truy cập dữ liệu | Chặn truy cập dữ liệu nhạy cảm |
+| **scout-block.cjs** | Khi tìm kiếm | Chặn tìm kiếm vào vùng cấm |
+
+### 📚 Hooks Context
+
+| Hook | Chạy Khi Nào | Làm Gì |
+|------|--------------|--------|
+| **backend-csharp-context.cjs** | Làm việc với C# | Load context cho C# |
+| **frontend-typescript-context.cjs** | Làm việc với TypeScript | Load context cho TS |
+| **design-system-context.cjs** | Thiết kế UI | Load design system |
+| **scss-styling-context.cjs** | Làm với SCSS | Load SCSS context |
+
+### 📢 Hooks Thông Báo
+
+| Hook | Chạy Khi Nào | Làm Gì |
+|------|--------------|--------|
+| **notify-waiting.js** | AI đang chờ input | Gửi thông báo cho user |
+| **session-end.cjs** | Kết thúc session | Ghi log, dọn dẹp |
+
+---
+
+## Cách Hooks Hoạt Động
+
+### Luồng hoạt động
+
+```
+   Sự kiện xảy ra (ví dụ: sửa file)
+              ↓
+   Hệ thống kiểm tra có hook nào cần chạy
+              ↓
+┌─────────────────────────────────┐
+│  Hook được kích hoạt            │
+│  (post-edit-prettier.cjs)       │
+│                                 │
+│  1. Nhận thông tin file         │
+│  2. Chạy Prettier format        │
+│  3. Lưu file đã format          │
+└─────────────────────────────────┘
+              ↓
+   Tiếp tục công việc bình thường
+```
+
+### Ví dụ cụ thể
+
+**Bạn sửa file `App.tsx`:**
+
+```
+1. Bạn lưu file
+2. Hook post-edit-prettier.cjs tự động chạy
+3. Prettier format lại code
+4. File được cập nhật với format chuẩn
+```
+
+Bạn không cần làm gì - tất cả tự động!
+
+---
+
+## Cấu Trúc Thư Mục Hooks
+
+```
+hooks/
+├── session-init.cjs            ← Khởi động session
+├── session-end.cjs             ← Kết thúc session
+├── post-edit-prettier.cjs      ← Format sau khi edit
+├── post-task-review.cjs        ← Review sau task
+├── workflow-router.cjs         ← Định tuyến workflow
+├── privacy-block.cjs           ← Bảo vệ privacy
+├── scout-block.cjs             ← Chặn tìm kiếm cấm
+├── dev-rules-reminder.cjs      ← Nhắc quy tắc
+├── notify-waiting.js           ← Thông báo chờ
+│
+├── lib/                        ← Thư viện dùng chung
+│   └── helpers.js
+│
+├── notifications/              ← Cấu hình thông báo
+│   └── config.json
+│
+├── docs/                       ← Tài liệu hooks
+│   └── how-to-create.md
+│
+└── tests/                      ← Tests cho hooks
+    └── *.test.js
+```
+
+---
+
+## Hooks Quan Trọng Nhất
+
+### 1. session-init.cjs - Khởi Động Session
+
+**Chạy khi:** Bạn bắt đầu làm việc với Claude
+
+**Làm gì:**
+- Đọc context dự án
+- Load settings
+- Kiểm tra có task dang dở không
+- Chào bạn và tóm tắt trạng thái
+
+---
+
+### 2. post-edit-prettier.cjs - Auto Format
+
+**Chạy khi:** Bạn sửa file code
+
+**Làm gì:**
+- Phát hiện loại file (JS, TS, CSS...)
+- Chạy Prettier với config phù hợp
+- Lưu file đã format
+
+**Lợi ích:** Code luôn format chuẩn, không cần manual format
+
+---
+
+### 3. post-task-review.cjs - Auto Review
+
+**Chạy khi:** Hoàn thành một task
+
+**Làm gì:**
+- Review code vừa viết
+- Check conventions
+- Báo cáo nếu có vấn đề
+
+**Lợi ích:** Phát hiện lỗi sớm, trước khi commit
+
+---
+
+### 4. privacy-block.cjs - Bảo Vệ Dữ Liệu
+
+**Chạy khi:** AI truy cập files
+
+**Làm gì:**
+- Kiểm tra file có nhạy cảm không (.env, secrets...)
+- Chặn truy cập nếu cấm
+- Log các truy cập
+
+**Lợi ích:** Bảo vệ dữ liệu nhạy cảm
+
+---
+
+## Tạo Hook Mới
+
+Nếu muốn tạo hook riêng:
+
+**1. Tạo file trong thư mục hooks:**
+```
+hooks/my-custom-hook.cjs
+```
+
+**2. Viết code hook:**
+```javascript
+// hooks/my-custom-hook.cjs
+
+module.exports = {
+  // Tên hook
+  name: 'my-custom-hook',
+  
+  // Chạy khi nào
+  trigger: 'post-edit', // hoặc 'pre-edit', 'session-start'...
+  
+  // Logic xử lý
+  async run(context) {
+    // Lấy thông tin file vừa sửa
+    const { filePath, content } = context;
+    
+    // Làm gì đó
+    console.log(`File ${filePath} đã được sửa`);
+    
+    // Trả về kết quả (nếu cần)
+    return { success: true };
+  }
+};
+```
+
+**3. Đăng ký hook** (trong settings.json)
+
+---
+
+## Tóm Tắt
+
+| Khái niệm | Giải thích |
+|-----------|------------|
+| **Hook là gì** | Code tự động chạy khi có sự kiện |
+| **Có bao nhiêu** | ~15 hooks có sẵn |
+| **Khi nào chạy** | Tự động theo trigger (edit, save, session start...) |
+| **Có thể tạo thêm** | Có, theo template trên |
+
+---
+
+## Lợi Ích Của Hooks
+
+| Không có Hooks | Có Hooks |
+|----------------|----------|
+| Phải manual format code | ✅ Tự động format |
+| Quên review trước commit | ✅ Tự động review |
+| Context bị mất giữa sessions | ✅ Tự động load context |
+| Có thể truy cập file nhạy cảm | ✅ Tự động chặn |
+
+---
+
+## Xem Thêm
+
+- [Scripts (Công cụ)](../scripts/README.md)
+- [Workflows (Quy trình)](../workflows/README.md)
+- [Settings (Cấu hình)](../settings.json)