thanh-kit 2.5.0 → 2.5.1

package/templates/skills/docs/references/init-workflow.md

@@ -0,0 +1,32 @@
+# Init Workflow
+
+## Phase 1: Parallel Codebase Scouting
+
+1. Scan the codebase and calculate the number of files with LOC in each directory (skip credentials, cache or external modules directories, such as `.claude`, `.opencode`, `.git`, `tests`, `node_modules`, `__pycache__`, `secrets`, etc.)
+2. Target directories **that actually exist** - adapt to project structure, don't hardcode paths
+3. Activate `ck:scout` skill to explore the code base and return detailed summary reports to the main agent
+4. Merge scout reports into context summary
+
+## Phase 2: Documentation Creation (docs-manager Agent)
+
+**CRITICAL:** You MUST spawn `docs-manager` agent via Task tool with merged reports. Do not wait for user input.
+
+Pass the gathered context to docs-manager agent to create initial documentation:
+- `README.md`: Update README with initial documentation (keep it under 300 lines)
+- `docs/project-overview-pdr.md`: Project overview and PDR (Product Development Requirements)
+- `docs/codebase-summary.md`: Codebase summary
+- `docs/code-standards.md`: Codebase structure and code standards
+- `docs/system-architecture.md`: System architecture
+- `docs/project-roadmap.md`: Project roadmap
+- `docs/deployment-guide.md` [optional]: Deployment guide
+- `docs/design-guidelines.md` [optional]: Design guidelines
+
+## Phase 3: Size Check (Post-Generation)
+
+After docs-manager completes:
+1. Run `wc -l docs/*.md 2>/dev/null | sort -rn` to check LOC
+2. Use `docs.maxLoc` from session context (default: 800)
+3. For files exceeding limit:
+   - Report which files exceed and by how much
+   - docs-manager should have already split proactively
+   - If still oversized, ask user: split now or accept as-is?

package/templates/skills/docs/references/summarize-workflow.md

@@ -0,0 +1,18 @@
+# Summarize Workflow
+
+Activate `ck:scout` skill to analyze the codebase and update `docs/codebase-summary.md` and respond with a summary report.
+
+## Arguments
+$1: Focused topics (default: all)
+$2: Should scan codebase (`Boolean`, default: `false`)
+
+## Focused Topics
+<focused_topics>$1</focused_topics>
+
+## Should Scan Codebase
+<should_scan_codebase>$2</should_scan_codebase>
+
+## Important
+- Use `docs/` directory as the source of truth for documentation.
+- Do not scan the entire codebase unless the user explicitly requests it.
+- **Do not** start implementing.

package/templates/skills/docs/references/update-workflow.md

@@ -0,0 +1,59 @@
+# Update Workflow
+
+## Phase 1: Parallel Codebase Scouting
+
+1. Scan the codebase and calculate the number of files with LOC in each directory (skip `.claude`, `.opencode`, `.git`, `tests`, `node_modules`, `__pycache__`, `secrets`, etc.)
+2. Target directories **that actually exist** - adapt to project structure
+3. Activate `ck:scout` skill to explore the code base and return detailed summary reports
+4. Merge scout reports into context summary
+
+## Phase 1.5: Parallel Documentation Reading
+
+**You (main agent) must spawn readers** - subagents cannot spawn subagents.
+
+1. Count docs: `ls docs/*.md 2>/dev/null | wc -l`
+2. Get LOC: `wc -l docs/*.md 2>/dev/null | sort -rn`
+3. Strategy:
+   - 1-3 files: Skip parallel reading, docs-manager reads directly
+   - 4-6 files: Spawn 2-3 `Explore` agents
+   - 7+ files: Spawn 4-5 `Explore` agents (max 5)
+4. Distribute files by LOC (larger files get dedicated agent)
+5. Each agent prompt: "Read these docs, extract: purpose, key sections, areas needing update. Files: {list}"
+6. Merge results into context for docs-manager
+
+## Phase 2: Documentation Update (docs-manager Agent)
+
+**CRITICAL:** You MUST spawn `docs-manager` agent via Task tool with merged reports and doc readings.
+
+Pass the gathered context to docs-manager agent to update documentation:
+- `README.md`: Update README (keep it under 300 lines)
+- `docs/project-overview-pdr.md`: Update project overview and PDR
+- `docs/codebase-summary.md`: Update codebase summary
+- `docs/code-standards.md`: Update codebase structure and code standards
+- `docs/system-architecture.md`: Update system architecture
+- `docs/project-roadmap.md`: Update project roadmap
+- `docs/deployment-guide.md` [optional]: Update deployment guide
+- `docs/design-guidelines.md` [optional]: Update design guidelines
+
+## Additional requests
+<additional_requests>
+  $ARGUMENTS
+</additional_requests>
+
+## Phase 3: Size Check (Post-Update)
+
+After docs-manager completes:
+1. Run `wc -l docs/*.md 2>/dev/null | sort -rn` to check LOC
+2. Use `docs.maxLoc` from session context (default: 800)
+3. For files exceeding limit: report and ask user
+
+## Phase 4: Documentation Validation (Post-Update)
+
+Run validation to detect potential hallucinations:
+1. Run: `node .claude/scripts/validate-docs.cjs docs/`
+2. Display validation report (warnings only, non-blocking)
+3. Checks: code references, internal links, config keys
+
+## Important
+- Use `docs/` directory as the source of truth.
+- **Do not** start implementing.

package/templates/skills/docs-seeker/SKILL.md

@@ -1,7 +1,8 @@
 ---
-name: docs-seeker
-description: "Search technical documentation using executable scripts to detect query type, fetch from llms.txt sources (context7.com), and analyze results. Use when user needs: (1) Topic-specific documentation (features/components/concepts), (2) Library/framework documentation, (3) GitHub repository analysis, (4) Documentation discovery with automated agent distribution strategy"
+name: ck:docs-seeker
+description: Search library/framework documentation via llms.txt (context7.com). Use for API docs, GitHub repository analysis, technical documentation lookup, latest library features.
 version: 3.1.0
+argument-hint: "[library-name] [topic]"
 ---
 
 # Documentation Discovery via Scripts

package/templates/skills/document-skills/docx/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: docx
-description: "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. When Claude needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks"
+name: ck:docx
+description: Create, edit, analyze .docx Word documents. Use for document creation, tracked changes, comments, formatting preservation, text extraction, template modification.
 license: Proprietary. LICENSE.txt has complete terms
 ---
 

package/templates/skills/document-skills/pdf/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: pdf
-description: Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents, and handling forms. When Claude needs to fill in a PDF form or programmatically process, generate, or analyze PDF documents at scale.
+name: ck:pdf
+description: Extract text/tables, create, merge, split PDFs. Fill PDF forms programmatically. Use for PDF processing, generation, form filling, document analysis, batch operations.
 license: Proprietary. LICENSE.txt has complete terms
 ---
 

package/templates/skills/document-skills/pptx/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: pptx
-description: "Presentation creation, editing, and analysis. When Claude needs to work with presentations (.pptx files) for: (1) Creating new presentations, (2) Modifying or editing content, (3) Working with layouts, (4) Adding comments or speaker notes, or any other presentation tasks"
+name: ck:pptx
+description: Create, edit, analyze .pptx PowerPoint files. Use for presentations, slides, layouts, speaker notes, template modification, content extraction, slide generation.
 license: Proprietary. LICENSE.txt has complete terms
 ---
 

package/templates/skills/document-skills/xlsx/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: xlsx
-description: "Comprehensive spreadsheet creation, editing, and analysis with support for formulas, formatting, data analysis, and visualization. When Claude needs to work with spreadsheets (.xlsx, .xlsm, .csv, .tsv, etc) for: (1) Creating new spreadsheets with formulas and formatting, (2) Reading or analyzing data, (3) Modify existing spreadsheets while preserving formulas, (4) Data analysis and visualization in spreadsheets, or (5) Recalculating formulas"
+name: ck:xlsx
+description: Create, edit, analyze spreadsheets (.xlsx, .csv, .tsv). Use for Excel formulas, data analysis, visualization, formatting, pivot tables, charts, formula recalculation.
 license: Proprietary. LICENSE.txt has complete terms
 ---
 

package/templates/skills/document-skills/xlsx/recalc.py

@@ -11,8 +11,9 @@ import os
 import platform
 from pathlib import Path
 
-# Windows UTF-8 compatibility
-sys.path.insert(0, str(Path.home() / '.claude' / 'scripts'))
+# Windows UTF-8 compatibility (works for both local and global installs)
+CLAUDE_ROOT = Path(__file__).parent.parent.parent.parent
+sys.path.insert(0, str(CLAUDE_ROOT / 'scripts'))
 try:
     from win_compat import ensure_utf8_stdout
     ensure_utf8_stdout()

package/templates/skills/find-skills/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: ck:find-skills
+description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
+argument-hint: "[capability or task description]"
+---
+
+# Find Skills
+
+This skill helps you discover and install skills from the open agent skills ecosystem.
+
+## When to Use This Skill
+
+Use this skill when the user:
+
+- Asks "how do I do X" where X might be a common task with an existing skill
+- Says "find a skill for X" or "is there a skill for X"
+- Asks "can you do X" where X is a specialized capability
+- Expresses interest in extending agent capabilities
+- Wants to search for tools, templates, or workflows
+- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
+
+## What is the Skills CLI?
+
+The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
+
+**Key commands:**
+
+- `npx skills find [query]` - Search for skills interactively or by keyword
+- `npx skills add <package>` - Install a skill from GitHub or other sources
+- `npx skills check` - Check for skill updates
+- `npx skills update` - Update all installed skills
+
+**Browse skills at:** https://skills.sh/
+
+## How to Help Users Find Skills
+
+### Step 1: Understand What They Need
+
+When a user asks for help with something, identify:
+
+1. The domain (e.g., React, testing, design, deployment)
+2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
+3. Whether this is a common enough task that a skill likely exists
+
+### Step 2: Search for Skills
+
+Run the find command with a relevant query:
+
+```bash
+npx skills find [query]
+```
+
+For example:
+
+- User asks "how do I make my React app faster?" → `npx skills find react performance`
+- User asks "can you help me with PR reviews?" → `npx skills find pr review`
+- User asks "I need to create a changelog" → `npx skills find changelog`
+
+The command will return results like:
+
+```
+Install with npx skills add <owner/repo@skill>
+
+vercel-labs/agent-skills@vercel-react-best-practices
+└ https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
+```
+
+### Step 3: Present Options to the User
+
+When you find relevant skills, present them to the user with:
+
+1. The skill name and what it does
+2. The install command they can run
+3. A link to learn more at skills.sh
+
+Example response:
+
+```
+I found a skill that might help! The "vercel-react-best-practices" skill provides
+React and Next.js performance optimization guidelines from Vercel Engineering.
+
+To install it:
+npx skills add vercel-labs/agent-skills@vercel-react-best-practices
+
+Learn more: https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
+```
+
+### Step 4: Offer to Install
+
+If the user wants to proceed, you can install the skill for them:
+
+```bash
+npx skills add <owner/repo@skill> -g -y
+```
+
+The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
+
+## Common Skill Categories
+
+When searching, consider these common categories:
+
+| Category        | Example Queries                          |
+| --------------- | ---------------------------------------- |
+| Web Development | react, nextjs, typescript, css, tailwind |
+| Testing         | testing, jest, playwright, e2e           |
+| DevOps          | deploy, docker, kubernetes, ci-cd        |
+| Documentation   | docs, readme, changelog, api-docs        |
+| Code Quality    | review, lint, refactor, best-practices   |
+| Design          | ui, ux, design-system, accessibility     |
+| Productivity    | workflow, automation, git                |
+
+## Tips for Effective Searches
+
+1. **Use specific keywords**: "react testing" is better than just "testing"
+2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
+3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
+
+## When No Skills Are Found
+
+If no relevant skills exist:
+
+1. Acknowledge that no existing skill was found
+2. Offer to help with the task directly using your general capabilities
+3. Suggest the user could create their own skill with `npx skills init`
+
+Example:
+
+```
+I searched for skills related to "xyz" but didn't find any matches.
+I can still help you with this task directly! Would you like me to proceed?
+
+If this is something you do often, you could create your own skill:
+npx skills init my-xyz-skill
+```

package/templates/skills/fix/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: ck:fix
+description: "ALWAYS activate this skill before fixing ANY bug, error, test failure, CI/CD issue, type error, lint, log error, UI issue, code problem."
+version: 1.2.0
+argument-hint: "[issue] --auto|--review|--quick|--parallel"
+---
+
+# Fixing
+
+Unified skill for fixing issues of any complexity with intelligent routing.
+
+## Arguments
+
+- `--auto` - Activate autonomous mode (**default**)
+- `--review` - Activate human-in-the-loop review mode
+- `--quick` - Activate quick mode
+- `--parallel` - Activate parallel mode: route to parallel `fullstack-developer` agents per issue
+
+## Workflow
+
+### Step 1: Mode Selection
+
+**First action:** If there is no "auto" keyword in the request, use `AskUserQuestion` to determine workflow mode:
+
+| Option | Recommend When | Behavior |
+|--------|----------------|----------|
+| **Autonomous** (default) | Simple/moderate issues | Auto-approve if score >= 9.5 & 0 critical |
+| **Human-in-the-loop Review** | Critical/production code | Pause for approval at each step |
+| **Quick** | Type errors, lint, trivial bugs | Fast debug → fix → review cycle |
+
+See `references/mode-selection.md` for AskUserQuestion format.
+
+### Step 2: Debug
+
+- Activate `ck:debug` skill.
+- Guess all possible root causes.
+- Spawn multiple `Explore` subagents in parallel to verify each hypothesis.
+- Create report with all findings for the next step.
+
+### Step 3: Complexity Assessment & Task Orchestration
+
+Classify before routing. See `references/complexity-assessment.md`.
+
+| Level | Indicators | Workflow |
+|-------|------------|----------|
+| **Simple** | Single file, clear error, type/lint | `references/workflow-quick.md` |
+| **Moderate** | Multi-file, root cause unclear | `references/workflow-standard.md` |
+| **Complex** | System-wide, architecture impact | `references/workflow-deep.md` |
+| **Parallel** | 2+ independent issues OR `--parallel` flag | Parallel `fullstack-developer` agents |
+
+**Task Orchestration (Moderate+ only):** After classifying, create native Claude Tasks for all phases upfront with dependencies. See `references/task-orchestration.md`.
+- Skip for Quick workflow (< 3 steps, overhead exceeds benefit)
+- Use `TaskCreate` with `addBlockedBy` for dependency chains
+- Update via `TaskUpdate` as each phase completes
+- For Parallel: create separate task trees per independent issue
+
+### Step 4: Fix Implementation & Verification
+
+- Implement fix per selected workflow, updating Tasks as phases complete.
+- Spawn multiple `Explore` subagents to verify no regressions.
+- Prevent future issues by adding comprehensive validation.
+
+### Step 5: Finalize (MANDATORY - never skip)
+
+1. Report summary: confidence score, changes, files
+2. `docs-manager` subagent → update `./docs` if changes warrant (NON-OPTIONAL)
+3. `TaskUpdate` → mark ALL Claude Tasks `completed`
+4. Ask user if they want to commit via `git-manager` subagent
+
+---
+
+## IMPORTANT: Skill/Subagent Activation Matrix
+
+See `references/skill-activation-matrix.md` for complete matrix.
+
+**Always activate:** `ck:debug` (all workflows)
+**Conditional:** `ck:problem-solving`, `ck:sequential-thinking`, `ck:brainstorm`, `ck:context-engineering`
+**Subagents:** `debugger`, `researcher`, `planner`, `code-reviewer`, `tester`, `Bash`
+**Parallel:** Multiple `Explore` agents for scouting, `Bash` agents for verification
+
+## Output Format
+
+Unified step markers:
+```
+✓ Step 0: [Mode] selected - [Complexity] detected
+✓ Step 1: Root cause identified - [summary]
+✓ Step 2: Fix implemented - [N] files changed
+✓ Step 3: Tests [X/X passed]
+✓ Step 4: Review [score]/10 - [status]
+✓ Step 5: Complete - [action taken]
+```
+
+## References
+
+Load as needed:
+- `references/mode-selection.md` - AskUserQuestion format for mode
+- `references/complexity-assessment.md` - Classification criteria
+- `references/task-orchestration.md` - Native Claude Task patterns for moderate+ workflows
+- `references/workflow-quick.md` - Quick: debug → fix → review
+- `references/workflow-standard.md` - Standard: full pipeline with Tasks
+- `references/workflow-deep.md` - Deep: research + brainstorm + plan with Tasks
+- `references/review-cycle.md` - Review logic (autonomous vs HITL)
+- `references/skill-activation-matrix.md` - When to activate each skill
+- `references/parallel-exploration.md` - Parallel Explore/Bash/Task coordination patterns
+
+**Specialized Workflows:**
+- `references/workflow-ci.md` - GitHub Actions/CI failures
+- `references/workflow-logs.md` - Application log analysis
+- `references/workflow-test.md` - Test suite failures
+- `references/workflow-types.md` - TypeScript type errors
+- `references/workflow-ui.md` - Visual/UI issues (requires design skills)

package/templates/skills/fix/references/complexity-assessment.md

@@ -0,0 +1,72 @@
+# Complexity Assessment
+
+Classify issue complexity before routing to workflow.
+
+## Classification Criteria
+
+### Simple (→ workflow-quick.md) — No Tasks
+
+**Indicators:**
+- Single file affected
+- Clear error message (type error, syntax, lint)
+- Keywords: `type`, `typescript`, `tsc`, `lint`, `eslint`, `syntax`
+- Obvious fix location
+- No investigation needed
+
+**Task usage:** Skip. < 3 steps, overhead exceeds benefit.
+
+**Examples:**
+- "Fix type error in auth.ts"
+- "ESLint errors after upgrade"
+- "Syntax error in config file"
+
+### Moderate (→ workflow-standard.md) — Use Tasks
+
+**Indicators:**
+- 2-5 files affected
+- Root cause unclear but localized
+- Needs debugging investigation
+- Keywords: `bug`, `broken`, `not working`, `fails sometimes`
+- Test failures with unclear cause
+
+**Task usage:** Create 6 phase tasks with dependencies. See `references/task-orchestration.md`.
+
+**Examples:**
+- "Login sometimes fails"
+- "API returns wrong data"
+- "Component not rendering correctly"
+
+### Complex (→ workflow-deep.md) — Use Tasks with Dependency Chains
+
+**Indicators:**
+- System-wide impact (5+ files)
+- Architecture decision needed
+- Research required for solution
+- Keywords: `architecture`, `refactor`, `system-wide`, `design issue`
+- Performance/security vulnerabilities
+- Multiple interacting components
+
+**Task usage:** Create 8 phase tasks. Steps 1+2 run parallel (debug+research). Full dependency chains. See `references/task-orchestration.md`.
+
+**Examples:**
+- "Memory leak in production"
+- "Database deadlocks under load"
+- "Security vulnerability in auth flow"
+
+### Parallel (→ multiple fullstack-developer agents) — Use Task Trees
+
+**Triggers:**
+- `--parallel` flag explicitly passed (activate parallel routing regardless of auto-classification)
+
+**Indicators:**
+- 2+ independent issues mentioned
+- Issues in different areas (frontend + backend, auth + payments)
+- No dependencies between issues
+- Keywords: list of issues, "and", "also", multiple error types
+
+**Task usage:** Create separate task trees per independent issue. Spawn `fullstack-developer` agent per tree. Agents coordinate via `TaskUpdate`/`TaskList`. See `references/task-orchestration.md`.
+
+**Examples:**
+- "Fix type errors AND update UI styling"
+- "Auth bug + payment integration issue"
+- "3 different test failures in unrelated modules"

package/templates/skills/fix/references/mode-selection.md

@@ -0,0 +1,46 @@
+# Mode Selection
+
+Use `AskUserQuestion` at start of fixing workflow.
+
+## AskUserQuestion Format
+
+```json
+{
+  "questions": [{
+    "question": "How should I handle the fix workflow?",
+    "header": "Fix Mode",
+    "options": [
+      {
+        "label": "Autonomous (Recommended)",
+        "description": "Auto-approve if quality high, only ask when stuck"
+      },
+      {
+        "label": "Human-in-the-loop",
+        "description": "Pause for approval at each major step"
+      },
+      {
+        "label": "Quick fix",
+        "description": "Fast debug-fix-review cycle for simple issues"
+      }
+    ],
+    "multiSelect": false
+  }]
+}
+```
+
+## Mode Recommendations
+
+| Issue Type | Recommended Mode |
+|------------|------------------|
+| Type errors, lint errors | Quick |
+| Single file bugs | Quick or Autonomous |
+| Multi-file, unclear root cause | Autonomous |
+| Production/critical code | Human-in-the-loop |
+| System-wide/architecture | Human-in-the-loop |
+| Security vulnerabilities | Human-in-the-loop |
+
+## Skip Mode Selection When
+
+- Issue is clearly trivial (type error keyword detected) → default Quick
+- User explicitly specified mode in prompt
+- Previous context already established mode