thanh-kit 2.5.1 → 2.5.2

package/templates/command-archive/preview.md

@@ -0,0 +1,283 @@
+---
+description: View files/directories OR generate visual explanations, slides, diagrams
+arguments:
+  - name: path
+    description: Path to file/directory to preview, OR topic for generation modes
+    required: false
+---
+
+Universal viewer + visual generator. View existing content OR generate new visual explanations.
+
+## Usage
+
+### View Mode (existing behavior)
+- `/preview <file.md>` - View markdown file in novel-reader UI
+- `/preview <directory/>` - Browse directory contents
+- `/preview --stop` - Stop running server
+
+### Generation Mode (new)
+- `/preview --explain <topic>` - Generate visual explanation (ASCII + Mermaid + prose)
+- `/preview --slides <topic>` - Generate presentation slides (one concept per slide)
+- `/preview --diagram <topic>` - Generate focused diagram (ASCII + Mermaid)
+- `/preview --ascii <topic>` - Generate ASCII-only diagram (terminal-friendly)
+
+## Examples
+
+```bash
+# View mode
+/preview plans/my-plan/plan.md     # View markdown file
+/preview plans/                    # Browse plans directory
+
+# Generation mode
+/preview --explain OAuth flow      # Generate OAuth explanation
+/preview --slides API architecture # Generate architecture slides
+/preview --diagram data flow       # Generate data flow diagram
+/preview --ascii auth process      # Generate ASCII-only diagram
+```
+
+## Argument Resolution
+
+When processing arguments, follow this priority order:
+
+1. **`--stop`** → Stop server (exit)
+2. **Generation flags** (`--explain`, `--slides`, `--diagram`, `--ascii`) → Generation mode
+3. **Resolve path from argument:**
+   - If argument is an explicit path → use directly
+   - If argument is a contextual reference (e.g., "that file", "the report", "this") → resolve from recent conversation context (look for file paths, URLs, or recently mentioned files)
+4. **Resolved path exists on filesystem** → View mode
+5. **Path doesn't exist or can't resolve** → Ask user to clarify which file they meant
+
+**Topic-to-slug conversion:**
+- Lowercase the topic
+- Replace spaces/special chars with hyphens
+- Remove non-alphanumeric except hyphens
+- Collapse multiple hyphens → single hyphen
+- Trim leading/trailing hyphens
+- **Max 80 chars** - truncate at word boundary if longer
+- If result is empty (topic was all special chars) → Error: ask for valid topic
+
+Example: `OAuth 2.0 Flow` → `oauth-2-0-flow.md`
+
+**Multiple flags:** If multiple generation flags provided, use first one; remaining treated as topic.
+Example: `/preview --explain --slides topic` → `--explain` mode, topic = "--slides topic"
+
+**Placeholder `{topic}`:** Replaced with original user input in title case (not the slug).
+
+## Execution
+
+**IMPORTANT:** Run server as Claude Code background task using `run_in_background: true` with the Bash tool. This makes the server visible in `/tasks` and manageable via `KillShell`.
+
+The skill is located at `.claude/skills/markdown-novel-viewer/`.
+
+### Stop Server
+
+If `--stop` flag is provided:
+
+```bash
+node .claude/skills/markdown-novel-viewer/scripts/server.cjs --stop
+```
+
+### Start Server
+
+Otherwise, run the `markdown-novel-viewer` server as CC background task with `--foreground` flag (keeps process alive for CC task management):
+
+```bash
+# Determine if path is file or directory
+INPUT_PATH="{{path}}"
+if [[ -d "$INPUT_PATH" ]]; then
+  # Directory mode - browse
+  node .claude/skills/markdown-novel-viewer/scripts/server.cjs \
+    --dir "$INPUT_PATH" \
+    --host 0.0.0.0 \
+    --open \
+    --foreground
+else
+  # File mode - view markdown
+  node .claude/skills/markdown-novel-viewer/scripts/server.cjs \
+    --file "$INPUT_PATH" \
+    --host 0.0.0.0 \
+    --open \
+    --foreground
+fi
+```
+
+**Critical:** When calling the Bash tool:
+- Set `run_in_background: true` to run as CC background task
+- Set `timeout: 300000` (5 minutes) to prevent premature termination
+- Parse JSON output and report URL to user
+
+Example Bash tool call:
+```json
+{
+  "command": "node .claude/skills/markdown-novel-viewer/scripts/server.cjs --dir \"path\" --host 0.0.0.0 --open --foreground",
+  "run_in_background": true,
+  "timeout": 300000,
+  "description": "Start preview server in background"
+}
+```
+
+After starting, parse the JSON output (e.g., `{"success":true,"url":"http://localhost:3456/view?file=...","networkUrl":"http://192.168.1.x:3456/view?file=..."}`) and report:
+- Local URL for browser access
+- Network URL for remote device access (if available)
+- Inform user that server is now running as CC background task (visible in `/tasks`)
+
+**CRITICAL:** MUST display the FULL URL including path and query string (e.g., `http://localhost:3456/view?file=/path/to/file.md`). NEVER truncate to just `host:port` (e.g., `http://localhost:3456`). The full URL is required for direct file access.
+
+---
+
+## Generation Mode
+
+When `--explain`, `--slides`, `--diagram`, or `--ascii` flag is provided:
+
+### Step 1: Determine Output Location
+
+1. Check if there's an active plan context (from `## Plan Context` in hook injection)
+2. If active plan exists: save to `{plan_dir}/visuals/{topic-slug}.md`
+3. If no active plan: save to `plans/visuals/{topic-slug}.md`
+4. Create `visuals/` directory if it doesn't exist
+
+### Step 2: Generate Content
+
+**Mermaid Diagram Syntax:**
+When generating ` ```mermaid ` code blocks, use `/mermaidjs-v11` skill for v11 syntax rules.
+
+**Essential rules (always apply):**
+- Quote node text with special characters: `A["text with /slashes"]`
+- Escape brackets in labels: `A["array[0]"]`
+
+Use the appropriate template based on flag:
+
+#### --explain (Visual Explanation)
+```markdown
+# Visual Explanation: {topic}
+
+## Overview
+Brief description of what we're explaining.
+
+## Quick View (ASCII)
+┌─────────────┐    ┌─────────────┐    ┌─────────────┐
+│ Component A │───>│ Component B │───>│ Component C │
+└─────────────┘    └─────────────┘    └─────────────┘
+
+## Detailed Flow
+\```mermaid
+sequenceDiagram
+    participant A as Component A
+    participant B as Component B
+    A->>B: Request
+    B-->>A: Response
+\```
+
+## Key Concepts
+1. **Concept A** - Explanation
+2. **Concept B** - Explanation
+
+## Code Example (if applicable)
+\```typescript
+// Relevant code snippet with comments
+\```
+```
+
+#### --slides (Presentation Format)
+```markdown
+# {Topic} - Visual Presentation
+
+---
+
+## Slide 1: Introduction
+- One concept per slide
+- Bullet points only
+
+---
+
+## Slide 2: The Problem
+\```mermaid
+flowchart TD
+    A[Problem] --> B[Impact]
+\```
+
+---
+
+## Slide 3: The Solution
+- Key point 1
+- Key point 2
+
+---
+
+## Slide 4: Summary
+Key takeaways...
+```
+
+#### --diagram (Focused Diagram)
+```markdown
+# Diagram: {topic}
+
+## ASCII Version
+┌──────────────────────────────────────────┐
+│               Architecture               │
+├─────────────┬──────────────┬─────────────┤
+│   Layer 1   │   Layer 2    │   Layer 3   │
+└─────────────┴──────────────┴─────────────┘
+
+## Mermaid Version
+\```mermaid
+flowchart TB
+    subgraph Layer1[Layer 1]
+        A[Component A]
+    end
+    subgraph Layer2[Layer 2]
+        B[Component B]
+    end
+    A --> B
+\```
+```
+
+#### --ascii (Terminal-Friendly Only)
+```
+┌────────────────────────────────────────────────────────┐
+│                    {Topic} Overview                    │
+├────────────────────────────────────────────────────────┤
+│                                                        │
+│   ┌─────────┐       ┌─────────┐       ┌─────────┐      │
+│   │  Input  │──────>│ Process │──────>│ Output  │      │
+│   └─────────┘       └─────────┘       └─────────┘      │
+│                                                        │
+│   Legend:                                              │
+│   ──────>  Data flow                                   │
+│   ──────   Connection                                  │
+│                                                        │
+└────────────────────────────────────────────────────────┘
+```
+
+### Step 3: Save and Preview
+
+1. Write generated content to determined path
+2. Start preview server with the generated file:
+```bash
+node .claude/skills/markdown-novel-viewer/scripts/server.cjs \
+  --file "<generated-file-path>" \
+  --host 0.0.0.0 \
+  --open \
+  --foreground
+```
+
+### Step 4: Report to User
+
+Report:
+- Generated file path
+- Preview URL (local + network)
+- Remind: file saved in plan's `visuals/` folder for future reference
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| Invalid topic (empty) | Ask user to provide a topic |
+| Flag without topic (`/preview --explain`) | Ask user: "Please provide a topic: `/preview --explain <topic>`" |
+| Topic becomes empty after sanitization | Ask user to provide topic with alphanumeric characters |
+| File write failure | Report error, suggest checking permissions |
+| Server startup failure | Check if port in use, try `/preview --stop` first |
+| No generation flag + unresolvable reference | Ask user to clarify which file they meant |
+| Existing file at output path | Overwrite with new content (no prompt) |
+| Server already running | Reuse existing server instance, just open new URL |
+| Parent `plans/` dir missing | Create directories recursively before write |

package/templates/command-archive/review/codebase/parallel.md

@@ -0,0 +1,122 @@
+---
+description: ⚡⚡⚡ Ultrathink edge cases, then parallel verify with code-reviewers
+argument-hint: [scope-or-prompt]
+---
+
+**Ultrathink** to exhaustively list ALL potential edge cases, then dispatch parallel `code-reviewer` agents to verify: <scope>$ARGUMENTS</scope>
+
+**IMPORTANT:** Activate needed skills. Ensure token efficiency. Sacrifice grammar for concision.
+
+## Workflow
+
+### 1. Ultrathink Edge Cases
+
+Main agent deeply analyzes the scope to LIST all potential edge cases FIRST:
+- Read `codebase-summary.md` for context
+- Use `/scout:ext` to find relevant files
+- **Think exhaustively** about what could go wrong:
+  - Null/undefined scenarios
+  - Boundary conditions (off-by-one, empty, max values)
+  - Error handling gaps
+  - Race conditions, async edge cases
+  - Input validation holes
+  - Security vulnerabilities
+  - Resource leaks
+  - Untested code paths
+
+**Output format:**
+```markdown
+## Edge Cases Identified
+
+### Category: [scope-area]
+1. [edge case description] → files: [file1, file2]
+2. [edge case description] → files: [file3]
+
+### Category: [another-area]
+1. [edge case description] → files: [file4, file5]
+```
+
+### 2. Categorize & Assign
+
+Group edge cases by similar scope for parallel verification:
+- Each category → one `code-reviewer` agent
+- Max 6 categories (merge small ones)
+- Each reviewer gets specific edge cases to VERIFY, not discover
+
+### 3. Parallel Verification
+
+Launch N `code-reviewer` subagents simultaneously:
+- Pass: category name, list of edge cases, relevant files
+- Task: **VERIFY** if each edge case is properly handled in code
+- Report: which edge cases are handled vs unhandled
+
+**Reviewer instruction:**
+```
+Verify these specific edge cases in the given files:
+[list of edge cases]
+
+For each, report:
+- ✅ Handled: [how it's handled]
+- ❌ Unhandled: [what's missing]
+- ⚠️ Partial: [what needs improvement]
+```
+
+### 4. Aggregate Results
+
+Collect all verification reports:
+```markdown
+## Edge Case Verification Report
+
+### Summary
+- Total edge cases: X
+- Handled: Y ✅
+- Unhandled: Z ❌
+- Partial: W ⚠️
+
+### Unhandled Edge Cases (Need Fix)
+| # | Edge Case | File | Status |
+|---|-----------|------|--------|
+| 1 | ...       | ...  | ❌     |
+
+### Partial Handling (Need Review)
+| # | Edge Case | File | Issue |
+|---|-----------|------|-------|
+| 1 | ...       | ...  | ...   |
+```
+
+### 5. Auto-Fix Pipeline
+
+**IF** unhandled/partial edge cases found:
+- Ask: "Found N unhandled edge cases. Fix with /fix --parallel? [Y/n]"
+- **IF yes:** Trigger `/fix --parallel` with unhandled list
+
+### 6. Final Report
+
+- Summary of verification
+- Ask: "Commit? [Y/n]" → use `git-manager`
+
+## Example
+
+```
+User: /review:codebase:parallel auth module
+
+1. Ultrathink → Lists 12 edge cases for auth:
+   - Empty password submission
+   - Token expiry during request
+   - Concurrent login attempts
+   - Invalid refresh token
+   ...
+
+2. Categorize → 3 groups:
+   - Login flow (4 cases)
+   - Token handling (5 cases)
+   - Session management (3 cases)
+
+3. Parallel → 3 code-reviewers verify simultaneously
+
+4. Aggregate → 8 handled, 3 unhandled, 1 partial
+
+5. Fix → User approves → /fix --parallel
+
+6. Final → Commit changes
+```

package/templates/{commands → command-archive}/test/ui.md

@@ -1,6 +1,6 @@
 ---
-description: ⚡⚡ Run UI tests on a website & generate a detailed report.
-argument-hint: [url] [options]
+description: '⚡⚡ Run UI tests on a website & generate a detailed report.'
+argument-hint: '[url] [options]'
 ---
 
 Activate the chrome-devtools skill.
@@ -70,7 +70,7 @@ node screenshot.js --url https://example.com/settings --output settings.png --cl
 - `--clear true` - Clear saved auth session
 
 ## Workflow
-- Use `planning` skill to organize the test plan & report in the current project directory.
+- Use `plan` 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

package/templates/{commands → command-archive}/use-mcp.md

@@ -9,7 +9,8 @@ Execute MCP operations via **Gemini CLI** to preserve context budget.
 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
+   # Read model from .claude/.ck.json: gemini.model (default: gemini-3-flash-preview)
+   echo "$ARGUMENTS. Return JSON only per GEMINI.md instructions." | gemini -y -m <gemini.model>
    ```
 
 2. **Fallback to mcp-manager subagent** (if Gemini CLI unavailable):
@@ -30,5 +31,8 @@ Execute MCP operations via **Gemini CLI** to preserve context budget.
 
 ```bash
 # BROKEN - deprecated -p flag skips MCP server connections!
-gemini -y -m gemini-2.5-flash -p "..."
+gemini -y -m <gemini.model> -p "..."
+
+# ALSO BROKEN - --model flag with -p
+gemini -y -p "..." --model gemini-3-flash-preview
 ```

package/templates/command-archive/worktree.md

@@ -0,0 +1,109 @@
+---
+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 Repo Info
+
+```bash
+node .claude/scripts/worktree.cjs info --json
+```
+
+Parse JSON response for: `repoType`, `baseBranch`, `projects`, `worktreeRoot`, `worktreeRootSource`.
+
+### Step 2: Detect Branch Prefix
+
+From user's description:
+- "fix", "bug", "error", "issue" → `fix`
+- "refactor", "restructure", "rewrite" → `refactor`
+- "docs", "documentation", "readme" → `docs`
+- "test", "spec", "coverage" → `test`
+- "chore", "cleanup", "deps" → `chore`
+- "perf", "performance", "optimize" → `perf`
+- Default → `feat`
+
+### Step 3: Convert to Slug
+
+"add authentication system" → `add-auth`
+"fix login bug" → `login-bug`
+Max 50 chars, kebab-case.
+
+### Step 4: Handle Monorepo
+
+If `repoType === "monorepo"` and project not specified, use AskUserQuestion:
+```javascript
+AskUserQuestion({
+  questions: [{
+    header: "Project",
+    question: "Which project for the worktree?",
+    options: projects.map(p => ({ label: p.name, description: p.path })),
+    multiSelect: false
+  }]
+})
+```
+
+### Step 5: Execute
+
+**Monorepo:**
+```bash
+node .claude/scripts/worktree.cjs create "<PROJECT>" "<SLUG>" --prefix <TYPE>
+```
+
+**Standalone:**
+```bash
+node .claude/scripts/worktree.cjs create "<SLUG>" --prefix <TYPE>
+```
+
+**Options:**
+- `--prefix` - Branch type: feat|fix|refactor|docs|test|chore|perf
+- `--worktree-root <path>` - Override default location (only if needed)
+- `--json` - JSON output
+- `--dry-run` - Preview
+
+### Step 6: Install Dependencies
+
+Based on project context, run in background:
+- `bun.lock` → `bun install`
+- `pnpm-lock.yaml` → `pnpm install`
+- `yarn.lock` → `yarn install`
+- `package-lock.json` → `npm install`
+- `poetry.lock` → `poetry install`
+- `requirements.txt` → `pip install -r requirements.txt`
+- `Cargo.toml` → `cargo build`
+- `go.mod` → `go mod download`
+
+## Commands
+
+| Command | Usage | Description |
+|---------|-------|-------------|
+| `create` | `create [project] <feature>` | Create worktree |
+| `remove` | `remove <name-or-path>` | Remove worktree |
+| `info` | `info` | Repo info with worktree location |
+| `list` | `list` | List worktrees |
+
+## Example
+
+```
+User: /worktree fix the login validation bug
+
+Claude: [Runs: node .claude/scripts/worktree.cjs info --json]
+        repoType: standalone
+        worktreeRoot: /home/user/worktrees
+        worktreeRootSource: sibling directory
+
+        [Prefix: fix, Slug: login-validation-bug]
+        [Runs: node .claude/scripts/worktree.cjs create "login-validation-bug" --prefix fix]
+
+Output: Worktree created at /home/user/worktrees/my-project-login-validation-bug
+```
+
+## Notes
+
+- Script auto-detects superproject, monorepo, and standalone repos
+- Default worktree location is smart: superproject > monorepo > sibling
+- Use `--worktree-root` only to override defaults
+- Env templates (`.env*.example`) auto-copied with `.example` suffix removed

package/templates/{workflows → rules}/development-rules.md

@@ -4,38 +4,30 @@
 **IMPORTANT:** You ALWAYS follow these principles: **YAGNI (You Aren't Gonna Need It) - KISS (Keep It Simple, Stupid) - DRY (Don't Repeat Yourself)**
 
 ## General
-
 - **File Naming**: Use kebab-case for file names with a meaningful name that describes the purpose of the file, doesn't matter if the file name is long, just make sure when LLMs read the file names while using Grep or other tools, they can understand the purpose of the file right away without reading the file content.
-- **File Size Management**: Keep individual code files under 300 lines for optimal context management
+- **File Size Management**: Keep individual code files under 200 lines for optimal context management
   - Split large files into smaller, focused components/modules
   - Use composition over inheritance for complex widgets
   - Extract utility functions into separate modules
   - Create dedicated service classes for business logic
-- Use `docs-seeker` skill for exploring latest docs of plugins/packages if needed
+- When looking for docs, activate `docs-seeker` skill (`context7` reference) for exploring latest docs.
 - Use `gh` bash command to interact with Github features if needed
 - Use `psql` bash command to query Postgres database for debugging if needed
 - Use `ai-multimodal` skill for describing details of images, videos, documents, etc. if needed
 - Use `ai-multimodal` skill and `imagemagick` skill for generating and editing images, videos, documents, etc. if needed
-- Use `sequential-thinking` skill and `debugging` skills for sequential thinking, analyzing code, debugging, etc. if needed
+- Use `sequential-thinking` and `debug` skills for sequential thinking, analyzing code, debugging, etc. if needed
 - **[IMPORTANT]** Follow the codebase structure and code standards in `./docs` during implementation.
 - **[IMPORTANT]** Do not just simulate the implementation or mocking them, always implement the real code.
 
 ## Code Quality Guidelines
-
 - Read and follow codebase structure and code standards in `./docs`
 - Don't be too harsh on code linting, but **make sure there are no syntax errors and code are compilable**
 - Prioritize functionality and readability over strict style enforcement and code formatting
 - Use reasonable code quality standards that enhance developer productivity
 - Use try catch error handling & cover security standards
 - Use `code-reviewer` agent to review code after every implementation
-- **[CRITICAL] Class Responsibility Rule:**
-  - Logic belongs in LOWEST layer: Entity/Model > Service > Component/Handler
-  - Backend: Entity mapping → Command.UpdateEntity() or DTO.MapToEntity(), NOT in Handler
-  - Frontend: Constants, column arrays, role lists → static properties in Model class, NOT in Component
-  - Frontend: Display logic (CSS class, status text) → instance getter in Model, NOT switch in Component
 
 ## Pre-commit/Push Rules
-
 - Run linting before commit
 - Run tests before push (DO NOT ignore failed tests just to pass the build or github actions)
 - Keep commits focused on the actual code changes
@@ -43,51 +35,18 @@
 - Create clean, professional commit messages without AI references. Use conventional commit format.
 
 ## Code Implementation
-
 - Write clean, readable, and maintainable code
 - Follow established architectural patterns
 - Implement features according to specifications
 - Handle edge cases and error scenarios
 - **DO NOT** create new enhanced files, update to the existing files directly.
 
-## Mandatory Post-Task Two-Pass Review Protocol
-
-**CRITICAL:** After ANY code changes (bug fix or feature), execute this protocol BEFORE task completion.
-
-### Pass 1: Initial Review
-
-1. Run `git diff` to examine unstaged changes
-2. Verify changes correctly implement the task requirements
-3. Check compliance with project conventions and best practices:
-   - Backend: repository patterns, validation fluent API, DTOs, event handlers
-   - Frontend: base classes, stores, BEM classes, untilDestroyed()
-4. Identify security vulnerabilities and edge cases
-5. Fix any issues found → mark `MADE_CHANGES = true`
-
-### Pass 2: Re-Review (Conditional)
-
-**ONLY IF Pass 1 made changes:**
-
-1. Run `git diff` again to verify all current changes
-2. Re-execute full review checklist on updated code
-3. Ensure corrections didn't introduce new issues
-4. Apply minimal, targeted fixes if needed
-
-### Quick Reference
-
-```bash
-# Execute review
-/review:post-task
-
-# Or use code-reviewer subagent for complex reviews
-Task tool → code-reviewer subagent
-```
-
-### Review Checklist Quick Reference
-
-- [ ] Task objective achieved correctly
-- [ ] No unrelated/unnecessary modifications
-- [ ] Follows project code conventions
-- [ ] No security vulnerabilities
-- [ ] Edge cases handled
-- [ ] Ready for commit
+## Visual Aids
+- Use `/preview --explain` when explaining unfamiliar code patterns or complex logic
+- Use `/preview --diagram` for architecture diagrams and data flow visualization
+- Use `/preview --slides` for step-by-step walkthroughs and presentations
+- Use `/preview --ascii` for terminal-friendly diagrams (no browser needed to understand)
+- **Plan context:** Active plan determined from `## Plan Context` in hook injection; visuals save to `{plan_dir}/visuals/`
+- If no active plan, fallback to `plans/visuals/` directory
+- For Mermaid diagrams, use `/mermaidjs-v11` skill for v11 syntax rules
+- See `primary-workflow.md` → Step 6 for workflow integration