thanh-kit 2.5.2 → 2.5.4

package/templates/commands/plan/two.md

@@ -0,0 +1,45 @@
+---
+description: ⚡⚡⚡⚡ Research & create an implementation plan with 2 approaches
+argument-hint: [task]
+---
+
+Think harder.
+Activate `planning` skill.
+
+## Your mission
+Use the `planner` subagent to create 2 detailed implementation plans for this following task:
+<task>
+ $ARGUMENTS
+</task>
+
+## Workflow
+1. First: Create a directory using naming pattern from `## Naming` section in injected context.
+   Make sure you pass the directory path to every subagent during the process.
+2. Follow strictly to the "Plan Creation & Organization" rules of `planning` skill.
+3. Use multiple `researcher` agents in parallel to research for this task, each agent research for a different aspect of the task and perform max 5 researches (max 5 tool calls).
+4. Use `scout` agent to search the codebase for files needed to complete the task.
+5. Main agent gathers all research and scout report filepaths, and pass them to `planner` subagent with the detailed instructions prompt to create an implementation plan of this task.
+  **Output:** Provide at least 2 implementation approaches with clear trade-offs, and explain the pros and cons of each approach, and provide a recommended approach.
+1. Main agent receives the implementation plan from `planner` subagent, and ask user to review the plan
+
+## Plan File Specification
+- Every `plan.md` MUST start with YAML frontmatter:
+  ```yaml
+  ---
+  title: "{Brief title}"
+  description: "{One sentence for card preview}"
+  status: pending
+  priority: P2
+  effort: {sum of phases, e.g., 4h}
+  branch: {current git branch}
+  tags: [relevant, tags]
+  created: {YYYY-MM-DD}
+  ---
+  ```
+
+## Important Notes
+**IMPORTANT:** Analyze the skills catalog and activate the skills that are needed for the task during the process.
+**IMPORTANT:** Sacrifice grammar for the sake of concision when writing reports.
+**IMPORTANT:** Ensure token efficiency while maintaining high quality.
+**IMPORTANT:** In reports, list any unresolved questions at the end, if any.
+**IMPORTANT**: **Do not** start implementing.

package/templates/commands/plan.md

@@ -0,0 +1,30 @@
+---
+description: ⚡⚡⚡ Intelligent plan creation with prompt enhancement
+argument-hint: [task]
+---
+
+## Your mission
+<task>
+$ARGUMENTS
+</task>
+
+## Pre-Creation Check (Active vs Suggested Plan Detection)
+
+Check the `## Plan Context` section in the injected context:
+- If "Plan:" shows a path → Active plan exists. Ask user: "Active plan found: {path}. Continue with this? [Y/n]"
+- If "Suggested:" shows a path → Branch-matched plan hint only. Ask user if they want to activate it or create new.
+- If "Plan: none" → Proceed to create new plan using naming pattern from `## Naming` section.
+
+## Workflow
+- Analyze the given task and use `AskUserQuestion` tool to ask for more details if needed.
+- Decide to use `/plan:fast` or `/plan:hard` SlashCommands based on the complexity.
+- Execute SlashCommand: `/plan:fast <detailed-instructions-prompt>` or `/plan:hard <detailed-instructions-prompt>`
+- Activate `planning` skill.
+- Note: `detailed-instructions-prompt` is **an enhanced prompt** that describes the task in detail based on the provided task description.
+
+## Important Notes
+**IMPORTANT:** Analyze the skills catalog and activate the skills that are needed for the task during the process.
+**IMPORTANT:** Sacrifice grammar for the sake of concision when writing reports.
+**IMPORTANT:** Ensure token efficiency while maintaining high quality.
+**IMPORTANT:** In reports, list any unresolved questions at the end, if any.
+**IMPORTANT**: **Do not** start implementing.

package/templates/commands/scout/ext.md

@@ -0,0 +1,39 @@
+---
+description: ⚡ Use external agentic tools to scout given directories
+argument-hint: [user-prompt] [scale]
+---
+
+## Purpose
+
+Utilize external agentic tools to scout given directories or explore the codebase for files needed to complete the task using a fast, token efficient agent.
+
+## Variables
+
+USER_PROMPT: $1
+SCALE: $2 (defaults to 3)
+RELEVANT_FILE_OUTPUT_DIR: Use `Report:` from `## Naming` section
+
+## Configuration
+
+Read Gemini model from `.claude/.ck.json`: `gemini.model` (default: `gemini-3-flash-preview`)
+
+## Workflow:
+- Write a prompt for 'SCALE' number of agents to the `Task` tool that will immediately call the `Bash` tool to run these commands to kick off your agents to conduct the search:
+  - `gemini -y -m <gemini.model> "[prompt]"` (if count <= 3)
+  - `opencode run "[prompt]" --model opencode/grok-code` (if count > 3 and count < 6)
+  - if count >= 6, spawn `Explore` subagents to search the codebase in parallel
+
+**Why use external agentic tools?**
+- External agentic tools are faster and more efficient when using LLMs with large context windows (1M+ tokens).
+
+**How to prompt the agents:**
+- If `gemini` or `opencode` is not available, ask the user if they want to install it:
+  - If **yes**, install it (if there are permission issues, instruct the user to install it manually, including authentication steps)
+  - If **no**, use the default `Explore` subagents.
+- IMPORTANT: Kick these agents off in parallel using the `Task` tool, analyze and divide folders for each agent to scout intelligently and quickly.
+- IMPORTANT: These agents are calling OTHER agentic coding tools to search the codebase. DO NOT call any search tools yourself.
+- IMPORTANT: That means with the `Task` tool, you'll immediately call the Bash tool to run the respective agentic coding tool (gemini, opencode, claude, etc.)
+- IMPORTANT: Instruct the agents to quickly search the codebase for files needed to complete the task. This isn't about a full blown search, just a quick search to find the files needed to complete the task.
+- Instruct the subagent to use a timeout of 3 minutes for each agent's bash call. Skip any agents that don't return within the timeout, don't restart them.
+- **IMPORTANT:** Sacrifice grammar for the sake of concision when writing reports.
+- **IMPORTANT:** In reports, list any unresolved questions at the end, if any.

package/templates/commands/scout.md

@@ -0,0 +1,28 @@
+---
+description: ⚡⚡ Scout given directories to respond to the user's requests
+argument-hint: [user-prompt] [scale]
+---
+
+## Purpose
+
+Search the codebase for files needed to complete the task using a fast, token efficient agent.
+
+## Variables
+
+USER_PROMPT: $1
+SCALE: $2 (defaults to 3)
+REPORT_OUTPUT_DIR: Use `Report:` from `## Naming` section
+
+## Workflow:
+
+- Write a prompt for 'SCALE' number of agents to the `Task` tool that will immediately call the `Bash` tool to run these commands to kick off your agents to conduct the search: spawn many `Explore` subagents to search the codebase in parallel based on the user's prompt.
+
+**How to prompt the agents:**
+- IMPORTANT: Kick these agents off in parallel using the `Task` tool, analyze and divide folders for each agent to scout intelligently and quickly.
+- IMPORTANT: Instruct the agents to quickly search the codebase for files needed to complete the task. This isn't about a full blown search, just a quick search to find the files needed to complete the task.
+- Instruct the subagent to use a timeout of 3 minutes for each agent's bash call. Skip any agents that don't return within the timeout, don't restart them.
+
+**How to write reports:**
+
+- **IMPORTANT:** Sacrifice grammar for the sake of concision when writing reports.
+- **IMPORTANT:** In reports, list any unresolved questions at the end, if any.

package/templates/commands/skill/add.md

@@ -0,0 +1,36 @@
+---
+description: Add new reference files or scripts to a skill
+argument-hint: [skill-name] [reference-or-script-prompt]
+---
+
+Think harder.
+Use `skill-creator` skill and `claude-code-guide` subagent.
+Use `docs-seeker` skills to search for documentation if needed.
+
+## Arguments
+$1: skill name (required, default: "")
+$2: reference or script prompt (required, default: "")
+If $1 or $2 is not provided, ask the user to provide it.
+
+## Your mission
+Add new reference files or scripts to a skill at `.claude/skills/$1` directory.
+
+## Requirements
+<reference-or-script-prompt>
+$2
+</reference-or-script-prompt>
+
+## Rules of Skill Creation:
+Base on the requirements:
+- 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.
+- If you're given nothing, use `AskUserQuestion` tool for clarifications and `researcher` subagent to research about the topic.
+- If you're given an URL, it's documentation page, use `Explore` subagent to explore every internal link and report back to main agent, don't skip any link.
+- If you receive a lot of URLs, use multiple `Explore` subagents to explore them in parallel, then report back to main agent.
+- If you receive a lot of files, use multiple `Explore` subagents to explore them in parallel, then report back to main agent.
+- If you're given a Github URL, use [`repomix`](https://repomix.com/guide/usage) command to summarize ([install it](https://repomix.com/guide/installation) if needed) and spawn multiple `Explore` subagents to explore it in parallel, then report back to main agent.
+
+**IMPORTANT:**
+- 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/skill/create.md

@@ -0,0 +1,29 @@
+---
+description: Create a new agent skill
+argument-hint: [prompt-or-llms-or-github-url]
+---
+
+Ultrathink.
+Use `skill-creator` skill and `claude-code-guide` subagent.
+Use `docs-seeker` skills to search for documentation if needed.
+
+## Your mission
+Create a new skill in `.claude/skills/` directory.
+
+## Requirements
+<user-prompt>$ARGUMENTS</user-prompt>
+
+## Rules of Skill Creation:
+Base on the requirements:
+- 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.
+- If you're given nothing, use `AskUserQuestion` tool for clarifications and `researcher` subagent to research about the topic.
+- If you're given an URL, it's documentation page, use `Explore` subagent to explore every internal link and report back to main agent, don't skip any link.
+- If you receive a lot of URLs, use multiple `Explore` subagents to explore them in parallel, then report back to main agent.
+- If you receive a lot of files, use multiple `Explore` subagents to explore them in parallel, then report back to main agent.
+- If you're given a Github URL, use [`repomix`](https://repomix.com/guide/usage) command to summarize ([install it](https://repomix.com/guide/installation) if needed) and spawn multiple `Explore` subagents to explore it in parallel, then report back to main agent.
+
+**IMPORTANT:**
+- 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/skill/fix-logs.md

@@ -0,0 +1,22 @@
+---
+description: Fix the agent skill based on `logs.txt` file.
+argument-hint: [prompt-or-path-to-skill]
+---
+
+Think harder.
+Use `skill-creator` skill and `claude-code-guide` subagent.
+Use `docs-seeker` skills to search for documentation if needed.
+
+## Your mission
+Fix the agent skill based on the current `logs.txt` file (in the project root directory).
+
+## Requirements
+<user-prompt>$ARGUMENTS</user-prompt>
+
+## Rules of Skill Fixing:
+Base on the requirements:
+- If you're given nothing, use `AskUserQuestion` tool for clarifications and `researcher` subagent to research about the topic.
+- If you're given an URL, it's documentation page, use `Explorer` subagent to explore every internal link and report back to main agent, don't skip any link.
+- If you receive a lot of URLs, use multiple `Explorer` subagents to explore them in parallel, then report back to main agent.
+- If you receive a lot of files, use multiple `Explorer` subagents to explore them in parallel, then report back to main agent.
+- If you're given a Github URL, use [`repomix`](https://repomix.com/guide/usage) command to summarize ([install it](https://repomix.com/guide/installation) if needed) and spawn multiple `Explorer` subagents to explore it in parallel, then report back to main agent.

package/templates/commands/skill/optimize/auto.md

@@ -0,0 +1,25 @@
+---
+description: Optimize an existing agent skill [auto]
+argument-hint: [skill-name] [prompt]
+---
+
+Think harder.
+Use `skill-creator` skill and `claude-code-guide` subagent.
+Use `docs-seeker` skills to search for documentation if needed.
+
+## Arguments
+SKILL: $1 (default: `*`)
+PROMPT: $2 (default: empty)
+
+## Your mission
+Optimize an existing skill in `.claude/skills/${SKILL}` directory. 
+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.
+
+**IMPORTANT:**
+- 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.
+
+## Additional instructions
+<additional-instructions>$PROMPT</additional-instructions>

package/templates/commands/skill/optimize.md

@@ -0,0 +1,34 @@
+---
+description: Optimize an existing agent skill
+argument-hint: [skill-name] [prompt]
+---
+
+Think harder.
+Use `skill-creator` skill and `claude-code-guide` subagent.
+Use `docs-seeker` skills to search for documentation if needed.
+
+## Arguments
+SKILL: $1 (default: `*`)
+PROMPT: $2 (default: empty)
+
+## Your mission
+Propose a plan to optimize an existing 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>
+
+## 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:**
+- 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/skill/update.md

@@ -0,0 +1,36 @@
+---
+description: Update an existing agent skill [auto]
+argument-hint: [skill-name] [prompt]
+---
+
+Think harder.
+Use `skill-creator` skill and `claude-code-guide` subagent.
+Use `docs-seeker` skills to search for documentation if needed.
+
+## Arguments
+SKILL: $1 (default: `*`)
+PROMPT: $2 (default: empty)
+
+## Your mission
+Update an existing skill or its reference files in `.claude/skills/${SKILL}` directory based on the user's prompt. 
+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.
+
+### Scopes
+- Project-scope: Current working project directory (e.g. `.claude/`)
+- User-scope: Home/user directory (e.g. `~/.claude/`)
+
+## IMPORTANT NOTES:
+- ALWAYS make changes to skills in the project-scope `.claude/skills/` directory (UNLESS you're allowed to).
+- DO NOT make any changes to skills in the home/user-scope `~/.claude/skills/` directory (UNLESS you're allowed to).
+- If you're given nothing, use `AskUserQuestion` tool for clarifications and `researcher` subagent to research about the topic.
+- If you're given an URL, it's documentation page, use `Explore` subagent to explore every internal link and report back to main agent, don't skip any link.
+- If you receive a lot of URLs, use multiple `Explore` subagents to explore them in parallel, then report back to main agent.
+- If you receive a lot of files, use multiple `Explore` subagents to explore them in parallel, then report back to main agent.
+- If you're given a Github URL, use [`repomix`](https://repomix.com/guide/usage) command to summarize ([install it](https://repomix.com/guide/installation) if needed) and spawn multiple `Explore` subagents to explore it in parallel, then report back to main agent.
+- 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.
+
+## Additional instructions
+<additional-instructions>$PROMPT</additional-instructions>

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.