thanh-kit 2.5.3 → 2.5.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thanh-kit",
-  "version": "2.5.3",
+  "version": "2.5.5",
   "description": "CLI tool to scaffold AI agent projects with pre-configured kits (Claude, OpenCode, Codex)",
   "type": "module",
   "bin": {

package/templates/.env.example

@@ -0,0 +1,100 @@
+# Claude Code - Global Environment Variables
+# Location: .claude/.env
+# Priority: LOWEST (overridden by skills/.env and skill-specific .env)
+# Scope: Project-wide configuration, global defaults
+# Setup: Copy to .claude/.env and configure
+
+# ============================================
+# Environment Variable Hierarchy
+# ============================================
+# Priority order (highest to lowest):
+# 1. process.env                    - Runtime environment (HIGHEST)
+# 2. .claude/skills/<skill>/.env    - Skill-specific overrides
+# 3. .claude/skills/.env            - Shared across all skills
+# 4. .claude/.env                   - Global defaults (this file, LOWEST)
+#
+# All skills use centralized resolver: ~/.claude/scripts/resolve_env.py
+# Debug hierarchy: python ~/.claude/scripts/resolve_env.py --show-hierarchy
+
+# ============================================
+# ClaudeKit API Key (for VidCap, ReviewWeb services)
+# ============================================
+# Get your API key from https://claudekit.cc/api-keys
+# Required for accessing ClaudeKit services via skills
+CLAUDEKIT_API_KEY=
+
+# ============================================
+# Context7 API Configuration (optional)
+# ============================================
+# Get your API key from https://context7.com/dashboard/api-keys
+CONTEXT7_API_KEY=
+
+# ============================================
+# Claude Code Notification Hooks
+# ============================================
+# Discord Webhook URL (for Discord notifications)
+# Get from: Server Settings → Integrations → Webhooks → New Webhook
+DISCORD_WEBHOOK_URL=
+
+# Telegram Bot Token (for Telegram notifications)
+# Get from: @BotFather in Telegram
+TELEGRAM_BOT_TOKEN=
+
+# Telegram Chat ID (your chat ID or group ID)
+# Get from: https://api.telegram.org/bot<BOT_TOKEN>/getUpdates
+TELEGRAM_CHAT_ID=
+
+# ============================================
+# AI/ML API Keys (Global Defaults)
+# ============================================
+# Google Gemini API (for ai-multimodal, docs-seeker skills)
+# Get from: https://aistudio.google.com/apikey
+GEMINI_API_KEY=
+
+# Vertex AI Configuration (Optional alternative to AI Studio)
+# GEMINI_USE_VERTEX=true
+# VERTEX_PROJECT_ID=
+# VERTEX_LOCATION=us-central1
+
+# OpenAI API Key (if using OpenAI-based skills)
+# OPENAI_API_KEY=
+
+# Anthropic API Key (if using Claude API directly)
+# ANTHROPIC_API_KEY=
+
+# ============================================
+# Development & CI/CD
+# ============================================
+# NODE_ENV=development
+# DEBUG=false
+# LOG_LEVEL=info
+
+# ============================================
+# Project Configuration
+# ============================================
+# PROJECT_NAME=claudekit-engineer
+# ENVIRONMENT=local
+
+# ============================================
+# Example Usage Scenarios
+# ============================================
+# Scenario 1: Global default for all skills
+# .claude/.env (this file):                GEMINI_API_KEY=global-dev-key
+# Result: All skills use global-dev-key
+#
+# Scenario 2: Override for all skills
+# .claude/.env (this file):                GEMINI_API_KEY=global-dev-key
+# .claude/skills/.env:                     GEMINI_API_KEY=skills-prod-key
+# Result: All skills use skills-prod-key
+#
+# Scenario 3: Skill-specific override
+# .claude/.env (this file):                GEMINI_API_KEY=global-key
+# .claude/skills/.env:                     GEMINI_API_KEY=shared-key
+# .claude/skills/ai-multimodal/.env:       GEMINI_API_KEY=high-quota-key
+# Result: ai-multimodal uses high-quota-key, other skills use shared-key
+#
+# Scenario 4: Runtime testing
+# export GEMINI_API_KEY=test-key
+# Result: All skills use test-key regardless of config files
+#
+# Priority: runtime > skill-specific > shared > global (this file)

package/templates/hooks/.logs/hook-log.jsonl

@@ -0,0 +1,26 @@
+{"ts":"2026-03-04T16:03:43.971Z","hook":"scout-block","tool":"Bash","dur":4,"status":"ok","exit":0,"error":""}
+{"ts":"2026-03-04T16:03:43.978Z","hook":"scout-block","tool":"Read","dur":3,"status":"ok","exit":0,"error":""}
+{"ts":"2026-03-04T16:03:56.874Z","hook":"scout-block","tool":"Glob","dur":3,"status":"ok","exit":0,"error":""}
+{"ts":"2026-03-04T16:03:56.880Z","hook":"scout-block","tool":"Bash","dur":7,"status":"block","exit":2,"error":""}
+{"ts":"2026-03-04T16:03:57.560Z","hook":"scout-block","tool":"Bash","dur":4,"status":"ok","exit":0,"error":""}
+{"ts":"2026-03-04T16:04:18.074Z","hook":"scout-block","tool":"Bash","dur":3,"status":"ok","exit":0,"error":""}
+{"ts":"2026-03-04T16:04:18.082Z","hook":"scout-block","tool":"Read","dur":3,"status":"ok","exit":0,"error":""}
+{"ts":"2026-03-04T16:04:26.893Z","hook":"scout-block","tool":"Bash","dur":7,"status":"block","exit":2,"error":""}
+{"ts":"2026-03-04T16:04:32.226Z","hook":"scout-block","tool":"Bash","dur":6,"status":"block","exit":2,"error":""}
+{"ts":"2026-03-04T16:04:32.234Z","hook":"scout-block","tool":"Read","dur":3,"status":"ok","exit":0,"error":""}
+{"ts":"2026-03-04T16:04:44.444Z","hook":"scout-block","tool":"Read","dur":3,"status":"ok","exit":0,"error":""}
+{"ts":"2026-03-04T16:04:44.445Z","hook":"scout-block","tool":"Read","dur":3,"status":"ok","exit":0,"error":""}
+{"ts":"2026-03-04T16:04:56.769Z","hook":"scout-block","tool":"Bash","dur":4,"status":"ok","exit":0,"error":""}
+{"ts":"2026-03-04T16:04:56.773Z","hook":"scout-block","tool":"Bash","dur":4,"status":"ok","exit":0,"error":""}
+{"ts":"2026-03-04T16:11:33.817Z","hook":"scout-block","tool":"Bash","dur":4,"status":"ok","exit":0,"error":""}
+{"ts":"2026-03-04T16:11:40.915Z","hook":"scout-block","tool":"Bash","dur":5,"status":"ok","exit":0,"error":""}
+{"ts":"2026-03-04T16:13:15.301Z","hook":"scout-block","tool":"Bash","dur":4,"status":"ok","exit":0,"error":""}
+{"ts":"2026-03-04T16:13:22.848Z","hook":"scout-block","tool":"Glob","dur":3,"status":"ok","exit":0,"error":""}
+{"ts":"2026-03-04T16:13:22.859Z","hook":"scout-block","tool":"Read","dur":3,"status":"ok","exit":0,"error":""}
+{"ts":"2026-03-04T16:13:25.718Z","hook":"scout-block","tool":"Read","dur":3,"status":"ok","exit":0,"error":""}
+{"ts":"2026-03-04T16:13:25.719Z","hook":"scout-block","tool":"Read","dur":3,"status":"ok","exit":0,"error":""}
+{"ts":"2026-03-04T16:13:54.959Z","hook":"scout-block","tool":"Bash","dur":4,"status":"ok","exit":0,"error":""}
+{"ts":"2026-03-04T16:16:20.243Z","hook":"scout-block","tool":"Bash","dur":4,"status":"ok","exit":0,"error":""}
+{"ts":"2026-03-04T16:18:06.224Z","hook":"scout-block","tool":"Read","dur":3,"status":"ok","exit":0,"error":""}
+{"ts":"2026-03-04T16:18:27.165Z","hook":"scout-block","tool":"Glob","dur":3,"status":"block","exit":2,"error":""}
+{"ts":"2026-03-04T16:18:27.166Z","hook":"scout-block","tool":"Bash","dur":2,"status":"ok","exit":0,"error":""}

package/templates/settings.local.json

@@ -0,0 +1,13 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(cat:*)",
+      "Bash(ls:*)",
+      "Bash(test:*)",
+      "Bash(chmod:*)",
+      "Bash(./install.sh)",
+      "Bash(.venv/bin/pip install:*)",
+      "Bash(grep:*)"
+    ]
+  }
+}

package/templates/skills/.env.example

@@ -47,6 +47,7 @@ GEMINI_API_KEY=
 # ============================================
 # Context7 MCP (Documentation search)
 # Skill: docs-seeker, mcp-management
+# Get your API key from https://context7.com/dashboard/api-keys
 # CONTEXT7_API_KEY=
 
 # ============================================

package/templates/AGENTS.md

@@ -1,104 +0,0 @@
-# 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

@@ -1,241 +0,0 @@
-# 🏠 .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