thanh-kit 2.5.0 → 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