thanh-kit 2.5.0 → 2.5.2

package/templates/skills/scout/references/external-scouting.md

@@ -0,0 +1,140 @@
+# External Scouting with Gemini/OpenCode
+
+Use external agentic tools for faster searches with large context windows (1M+ tokens).
+
+## Tool Selection
+
+```
+SCALE <= 3  → gemini CLI
+SCALE 4-5   → opencode CLI
+SCALE >= 6  → Use internal scouting instead
+```
+
+## Configuration
+
+Read from `.claude/.ck.json`:
+```json
+{
+  "gemini": {
+    "model": "gemini-3-flash-preview"
+  }
+}
+```
+
+Default model: `gemini-3-flash-preview`
+
+## Gemini CLI (SCALE <= 3)
+
+### Command
+```bash
+gemini -y -m <model> "[prompt]"
+```
+
+### Example
+```bash
+gemini -y -m gemini-3-flash-preview "Search src/ for authentication files. List paths with brief descriptions."
+```
+
+## OpenCode CLI (SCALE 4-5)
+
+### Command
+```bash
+opencode run "[prompt]" --model opencode/grok-code
+```
+
+### Example
+```bash
+opencode run "Find all payment-related files in lib/ and api/" --model opencode/grok-code
+```
+
+## Installation Check
+
+Before using, verify tools installed:
+```bash
+which gemini
+which opencode
+```
+
+If not installed, ask user:
+1. **Yes** - Provide installation instructions (may need manual auth steps)
+2. **No** - Fall back to Explore subagents (`internal-scouting.md`)
+
+## Spawning Parallel Bash Agents
+
+Use `Task` tool with `subagent_type: "Bash"` to spawn parallel agents:
+
+```
+Task 1: subagent_type="Bash", prompt="Run: gemini -y -m gemini-3-flash-preview '[prompt1]'"
+Task 2: subagent_type="Bash", prompt="Run: gemini -y -m gemini-3-flash-preview '[prompt2]'"
+Task 3: subagent_type="Bash", prompt="Run: gemini -y -m gemini-3-flash-preview '[prompt3]'"
+```
+
+Spawn all in single message for parallel execution.
+
+## Prompt Guidelines
+
+- Be specific about directories to search
+- Request file paths with descriptions
+- Set clear scope boundaries
+- Ask for patterns/relationships if relevant
+
+## Example Workflow
+
+User: "Find database migration files"
+
+Spawn 3 parallel Bash agents via Task tool:
+```
+Task 1 (Bash): "Run: gemini -y -m gemini-3-flash-preview 'Search db/, migrations/ for migration files'"
+Task 2 (Bash): "Run: gemini -y -m gemini-3-flash-preview 'Search lib/, src/ for database schema files'"
+Task 3 (Bash): "Run: gemini -y -m gemini-3-flash-preview 'Search config/ for database configuration'"
+```
+
+## Reading File Content
+
+When needing to read file content, use chunking to stay within context limits (<150K tokens safe zone).
+
+### Step 1: Get Line Counts
+```bash
+wc -l path/to/file1.ts path/to/file2.ts path/to/file3.ts
+```
+
+### Step 2: Calculate Chunks
+- **Target:** ~500 lines per chunk (safe for most files)
+- **Max files per agent:** 3-5 small files OR 1 large file chunked
+
+**Chunking formula:**
+```
+chunks = ceil(total_lines / 500)
+lines_per_chunk = ceil(total_lines / chunks)
+```
+
+### Step 3: Spawn Parallel Bash Agents
+
+**Small files (<500 lines each):**
+```
+Task 1: subagent_type="Bash", prompt="cat file1.ts file2.ts"
+Task 2: subagent_type="Bash", prompt="cat file3.ts file4.ts"
+```
+
+**Large file (>500 lines) - use sed for ranges:**
+```
+Task 1: subagent_type="Bash", prompt="sed -n '1,500p' large-file.ts"
+Task 2: subagent_type="Bash", prompt="sed -n '501,1000p' large-file.ts"
+Task 3: subagent_type="Bash", prompt="sed -n '1001,1500p' large-file.ts"
+```
+
+### Chunking Decision Tree
+```
+File < 500 lines     → Read entire file
+File 500-1500 lines  → Split into 2-3 chunks
+File > 1500 lines    → Split into ceil(lines/500) chunks
+```
+
+Spawn all in single message for parallel execution.
+
+## Timeout and Error Handling
+
+- Set 3-minute timeout per bash call
+- Skip timed-out agents
+- Don't restart failed agents
+- On persistent failures, fall back to internal scouting

package/templates/skills/scout/references/internal-scouting.md

@@ -0,0 +1,119 @@
+# Internal Scouting with Explore Subagents
+
+Use Explore subagents when SCALE >= 6 or external tools unavailable.
+
+## How It Works
+
+Spawn multiple `Explore` subagents via `Task` tool to search codebase in parallel.
+
+## Task Tool Configuration
+
+```
+subagent_type: "Explore"
+```
+
+## Prompt Template
+
+```
+Quickly scout {DIRECTORY} for files related to: {USER_PROMPT}
+
+Instructions:
+- Search for relevant files matching the task
+- Use Glob/Grep for file discovery
+- List files with brief descriptions
+- Timeout: 3 minutes max
+- Skip if timeout reached
+
+Report format:
+## Found Files
+- `path/file.ext` - description
+
+## Patterns
+- Key patterns observed
+```
+
+## Spawning Strategy
+
+### Directory Division
+Split codebase logically:
+- `src/` - Source code
+- `lib/` - Libraries
+- `tests/` - Test files
+- `config/` - Configuration
+- `api/` - API routes
+
+### Parallel Execution
+- Spawn all agents in single `Task` tool call
+- Each agent gets distinct directory scope
+- No overlap between agents
+
+## Example
+
+User prompt: "Find authentication-related files"
+
+```
+Agent 1: Scout src/auth/, src/middleware/ for auth files
+Agent 2: Scout src/api/, src/routes/ for auth endpoints
+Agent 3: Scout tests/ for auth tests
+Agent 4: Scout lib/, utils/ for auth utilities
+Agent 5: Scout config/ for auth configuration
+Agent 6: Scout types/, interfaces/ for auth types
+```
+
+## Timeout Handling
+
+- Set 3-minute timeout per agent
+- Skip non-responding agents
+- Don't restart timed-out agents
+- Aggregate available results
+
+## Reading File Content
+
+When needing to read file content, use chunking to stay within context limits (<150K tokens safe zone).
+
+### Step 1: Get Line Counts
+```bash
+wc -l path/to/file1.ts path/to/file2.ts path/to/file3.ts
+```
+
+### Step 2: Calculate Chunks
+- **Target:** ~500 lines per chunk (safe for most files)
+- **Max files per agent:** 3-5 small files OR 1 large file chunked
+
+**Chunking formula:**
+```
+chunks = ceil(total_lines / 500)
+lines_per_chunk = ceil(total_lines / chunks)
+```
+
+### Step 3: Spawn Parallel Bash Agents
+
+**Small files (<500 lines each):**
+```
+Task 1: subagent_type="Bash", prompt="cat file1.ts file2.ts"
+Task 2: subagent_type="Bash", prompt="cat file3.ts file4.ts"
+```
+
+**Large file (>500 lines) - use sed for ranges:**
+```
+Task 1: subagent_type="Bash", prompt="sed -n '1,500p' large-file.ts"
+Task 2: subagent_type="Bash", prompt="sed -n '501,1000p' large-file.ts"
+Task 3: subagent_type="Bash", prompt="sed -n '1001,1500p' large-file.ts"
+```
+
+### Chunking Decision Tree
+```
+File < 500 lines     → Read entire file
+File 500-1500 lines  → Split into 2-3 chunks
+File > 1500 lines    → Split into ceil(lines/500) chunks
+```
+
+Spawn all in single message for parallel execution.
+
+## Result Aggregation
+
+Combine results from all agents:
+1. Deduplicate file paths
+2. Merge descriptions
+3. Note any gaps/timeouts
+4. List unresolved questions

package/templates/skills/scout/references/task-management-scouting.md

@@ -0,0 +1,125 @@
+# Scout Task Management Patterns
+
+Track parallel scout agent execution via Claude Native Tasks (TaskCreate, TaskUpdate, TaskList).
+
+## When to Create Tasks
+
+| Agents | Create Tasks? | Rationale |
+|--------|--------------|-----------|
+| ≤ 2    | No           | Overhead exceeds benefit, finishes quickly |
+| ≥ 3    | Yes          | Meaningful coordination, progress monitoring |
+
+## Task Registration Flow
+
+```
+TaskList()                          // Check for existing scout tasks
+  → Found tasks?  → Skip creation, reuse existing
+  → Empty?        → TaskCreate per agent (see schema below)
+```
+
+## Metadata Schema
+
+```
+TaskCreate(
+  subject: "Scout {directory} for {target}",
+  activeForm: "Scouting {directory}",
+  description: "Search {directories} for {patterns}",
+  metadata: {
+    agentType: "Explore",        // "Explore" (internal) or "Bash" (external)
+    scope: "src/auth/,src/middleware/",
+    scale: 6,
+    agentIndex: 1,               // 1-indexed position
+    totalAgents: 6,
+    toolMode: "internal",        // "internal" or "external"
+    priority: "P2",              // Always P2 for scout coordination
+    effort: "3m"                 // Fixed timeout per agent
+  }
+)
+```
+
+### Required Fields
+
+- `agentType` — Subagent type: `"Explore"` for internal, `"Bash"` for external
+- `scope` — Comma-separated directory boundaries for this agent
+- `scale` — Total SCALE value determined in Step 1
+- `agentIndex` / `totalAgents` — Position tracking (e.g., 3 of 6)
+- `toolMode` — `"internal"` or `"external"`
+- `priority` — Always `"P2"` (scout = coordination, not primary work)
+- `effort` — Always `"3m"` (fixed timeout)
+
+### Optional Fields
+
+- `searchPatterns` — Key patterns searched (aids debugging)
+- `externalTool` — If external: `"gemini"` or `"opencode"`
+
+## Task Lifecycle
+
+```
+Step 3: TaskCreate per agent     → status: pending
+Step 4: Before spawning agent    → TaskUpdate → status: in_progress
+Step 5: Agent returns report     → TaskUpdate → status: completed
+Step 5: Agent times out (3m)     → Keep in_progress, add error metadata
+```
+
+### Timeout Handling
+
+```
+TaskUpdate(taskId, {
+  metadata: { ...existing, error: "timeout" }
+})
+// Task stays in_progress — distinguishes timeout from incomplete
+// Log in final report's "Unresolved Questions" section
+```
+
+## Examples
+
+### Internal Scouting (SCALE=6)
+
+```
+// Step 3: Register 6 tasks
+TaskCreate(subject: "Scout src/auth/ for auth files",
+  activeForm: "Scouting src/auth/",
+  metadata: { agentType: "Explore", scope: "src/auth/", scale: 6,
+              agentIndex: 1, totalAgents: 6, toolMode: "internal",
+              priority: "P2", effort: "3m" })  // → taskId1
+
+// Repeat for agents 2-6 with different scopes
+
+// Step 4: Spawn agents
+TaskUpdate(taskId1, { status: "in_progress" })
+// ... spawn all Explore subagents in single Task tool call
+
+// Step 5: Collect
+TaskUpdate(taskId1, { status: "completed" })  // report received
+TaskUpdate(taskId3, { metadata: { error: "timeout" } })  // timed out
+```
+
+### External Scouting (SCALE=3, gemini)
+
+```
+TaskCreate(subject: "Scout db/ for migrations via gemini",
+  activeForm: "Scouting db/ via gemini",
+  metadata: { agentType: "Bash", scope: "db/,migrations/", scale: 3,
+              agentIndex: 1, totalAgents: 3, toolMode: "external",
+              externalTool: "gemini", priority: "P2", effort: "3m" })
+```
+
+## Integration with Cook/Planning
+
+Scout tasks are **independent** from cook/planning phase tasks — NOT parent-child.
+
+**Rationale:** Different lifecycle. Scout completes before cook continues. Mixing creates confusion in TaskList.
+
+**Sequence when cook spawns scout:**
+1. Cook Step 2 → spawns planner → planner spawns scout
+2. Scout registers its own tasks (Step 3), executes (Step 4-5)
+3. Scout returns aggregated report → planner continues
+4. Cook Step 3 hydrates phase tasks (separate from scout tasks)
+
+## Quality Check Output
+
+After registration: `✓ Registered [N] scout tasks ([internal|external] mode, SCALE={scale})`
+
+## Error Handling
+
+If `TaskCreate` fails: log warning, continue without task tracking. Scout remains fully functional — tasks add observability, not functionality.

package/templates/skills/sequential-thinking/SKILL.md

@@ -1,8 +1,9 @@
 ---
-name: sequential-thinking
-description: Apply structured, reflective problem-solving for complex tasks requiring multi-step analysis, revision capability, and hypothesis verification. Use for complex problem decomposition, adaptive planning, analysis needing course correction, problems with unclear scope, multi-step solutions, and hypothesis-driven work.
+name: ck:sequential-thinking
+description: Apply step-by-step analysis for complex problems with revision capability. Use for multi-step reasoning, hypothesis verification, adaptive planning, problem decomposition, course correction.
 version: 1.0.0
 license: MIT
+argument-hint: "[problem to analyze step-by-step]"
 ---
 
 # Sequential Thinking

package/templates/skills/shader/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: ck:shader
+description: "Write GLSL fragment shaders for procedural graphics. Topics: shapes (SDF), patterns, noise (Perlin/simplex/cellular), fBm, colors (HSB/RGB), matrices, gradients, animations. Use for generative art, textures, visual effects, WebGL, Three.js shaders."
+version: 1.0.0
+argument-hint: "[effect or pattern]"
+---
+
+# GLSL Fragment Shaders
+
+Write GPU-accelerated fragment shaders for procedural graphics, textures, and visual effects.
+
+## When to Use
+
+- Creating procedural textures (wood, marble, clouds, terrain)
+- Drawing shapes with distance fields (SDF)
+- Generating patterns, noise, gradients
+- Building visual effects and animations
+- Writing custom shaders for Three.js, WebGL, Processing
+
+## Core Concepts
+
+Fragment shaders execute **simultaneously on every pixel**. Each thread:
+- Receives pixel position via `gl_FragCoord`
+- Returns color via `gl_FragColor` (vec4: RGBA 0.0-1.0)
+- Cannot communicate with other threads (stateless)
+
+## Standard Uniforms
+
+```glsl
+uniform float u_time;       // Elapsed seconds
+uniform vec2 u_resolution;  // Canvas size (width, height)
+uniform vec2 u_mouse;       // Mouse position in pixels
+```
+
+Normalize coordinates: `vec2 st = gl_FragCoord.xy / u_resolution;`
+
+## Essential Functions
+
+| Function | Purpose | Example |
+|----------|---------|---------|
+| `mix(a,b,t)` | Linear interpolate | `mix(red, blue, 0.5)` |
+| `step(edge,x)` | Hard threshold | `step(0.5, st.x)` |
+| `smoothstep(e0,e1,x)` | Smooth threshold | `smoothstep(0.2, 0.8, st.x)` |
+| `fract(x)` | Fractional part | `fract(st * 3.0)` for tiling |
+| `mod(x,y)` | Modulo | `mod(st.x, 0.25)` |
+| `clamp(x,min,max)` | Constrain value | `clamp(col, 0.0, 1.0)` |
+| `length(v)` | Vector magnitude | `length(st - 0.5)` |
+| `distance(a,b)` | Euclidean distance | `distance(st, center)` |
+| `dot(a,b)` | Dot product | `dot(normal, lightDir)` |
+| `normalize(v)` | Unit vector | `normalize(direction)` |
+| `atan(y,x)` | Angle (radians) | `atan(st.y-0.5, st.x-0.5)` |
+| `sin/cos/pow/abs` | Math | Hardware-accelerated |
+
+## Quick Patterns
+
+**Circle:**
+```glsl
+float d = distance(st, vec2(0.5));
+float circle = 1.0 - smoothstep(0.2, 0.21, d);
+```
+
+**Rectangle:**
+```glsl
+vec2 bl = step(vec2(0.1), st);
+vec2 tr = step(vec2(0.1), 1.0 - st);
+float rect = bl.x * bl.y * tr.x * tr.y;
+```
+
+**Tiling:**
+```glsl
+st = fract(st * 4.0);  // 4x4 grid
+```
+
+**Animation:**
+```glsl
+float wave = sin(st.x * 10.0 + u_time) * 0.5 + 0.5;
+```
+
+## References (Progressive Disclosure)
+
+### Fundamentals
+- `references/glsl-fundamentals-data-types-vectors-precision-coordinates.md`
+- `references/glsl-shaping-functions-step-smoothstep-curves-interpolation.md`
+
+### Drawing
+- `references/glsl-colors-rgb-hsb-gradients-mixing-color-spaces.md`
+- `references/glsl-shapes-sdf-circles-rectangles-polar-distance-fields.md`
+- `references/glsl-shapes-polygon-star-polar-sdf-combinations.md`
+
+### Procedural
+- `references/glsl-patterns-tiling-fract-matrices-transformations.md`
+- `references/glsl-pattern-symmetry-truchet-domain-warping.md`
+- `references/glsl-noise-random-perlin-simplex-cellular-voronoi.md`
+- `references/glsl-cellular-voronoi-worley-noise-patterns.md`
+- `references/glsl-fbm-fractional-brownian-motion-turbulence-octaves.md`
+- `references/glsl-procedural-textures-clouds-marble-wood-terrain.md`
+
+### API Reference
+- `references/glsl-shader-builtin-functions-complete-api-reference.md`
+
+## Tools
+
+- **Online Editor:** editor.thebookofshaders.com
+- **glslViewer:** CLI tool for running .frag files
+- **glslCanvas:** HTML embed for live shaders
+- **ShaderToy:** iTime, iResolution, iMouse uniforms
+
+## External Resources
+
+- The Book of Shaders: https://thebookofshaders.com
+- LYGIA Library: https://lygia.xyz (reusable shader functions)
+- ShaderToy: https://shadertoy.com
+- Inigo Quilez Articles: https://iquilezles.org/articles/

package/templates/skills/shader/references/glsl-cellular-voronoi-worley-noise-patterns.md

@@ -0,0 +1,142 @@
+# Cellular and Voronoi Noise
+
+Distance-based noise for organic cell patterns. See `glsl-noise-random-perlin-simplex-cellular-voronoi.md` for random functions.
+
+## Basic Cellular Noise
+
+Distance to nearest feature point:
+
+```glsl
+float cellularNoise(vec2 st) {
+    vec2 i = floor(st);
+    vec2 f = fract(st);
+
+    float minDist = 1.0;
+
+    // Check 3x3 neighborhood
+    for (int y = -1; y <= 1; y++) {
+        for (int x = -1; x <= 1; x++) {
+            vec2 neighbor = vec2(float(x), float(y));
+            vec2 point = random2(i + neighbor);
+            vec2 diff = neighbor + point - f;
+            float dist = length(diff);
+            minDist = min(minDist, dist);
+        }
+    }
+
+    return minDist;
+}
+```
+
+## Voronoi with Cell ID
+
+```glsl
+vec3 voronoi(vec2 st) {
+    vec2 i = floor(st);
+    vec2 f = fract(st);
+
+    float minDist = 1.0;
+    vec2 minPoint;
+
+    for (int y = -1; y <= 1; y++) {
+        for (int x = -1; x <= 1; x++) {
+            vec2 neighbor = vec2(float(x), float(y));
+            vec2 point = random2(i + neighbor);
+            vec2 diff = neighbor + point - f;
+            float dist = length(diff);
+            if (dist < minDist) {
+                minDist = dist;
+                minPoint = i + neighbor + point;
+            }
+        }
+    }
+
+    // Returns: distance, cell id x, cell id y
+    return vec3(minDist, minPoint);
+}
+
+// Color cells by ID
+vec3 voronoiColor(vec2 st, float scale) {
+    vec3 v = voronoi(st * scale);
+    return vec3(random(v.yz), random(v.yz + 1.0), random(v.yz + 2.0));
+}
+```
+
+## Worley Noise (F1, F2)
+
+```glsl
+vec2 worleyNoise(vec2 st) {
+    vec2 i = floor(st);
+    vec2 f = fract(st);
+
+    float f1 = 1.0;  // Nearest
+    float f2 = 1.0;  // Second nearest
+
+    for (int y = -1; y <= 1; y++) {
+        for (int x = -1; x <= 1; x++) {
+            vec2 neighbor = vec2(float(x), float(y));
+            vec2 point = random2(i + neighbor);
+            float dist = length(neighbor + point - f);
+
+            if (dist < f1) {
+                f2 = f1;
+                f1 = dist;
+            } else if (dist < f2) {
+                f2 = dist;
+            }
+        }
+    }
+
+    return vec2(f1, f2);
+}
+```
+
+## Worley Variations
+
+```glsl
+float worleyF1(vec2 st) { return worleyNoise(st).x; }
+float worleyEdges(vec2 st) { vec2 w = worleyNoise(st); return w.y - w.x; }
+float worleyBlobs(vec2 st) { vec2 w = worleyNoise(st); return w.x * w.y; }
+```
+
+## Animated Voronoi
+
+```glsl
+float animatedVoronoi(vec2 st, float time) {
+    vec2 i = floor(st);
+    vec2 f = fract(st);
+
+    float minDist = 1.0;
+
+    for (int y = -1; y <= 1; y++) {
+        for (int x = -1; x <= 1; x++) {
+            vec2 neighbor = vec2(float(x), float(y));
+            vec2 point = random2(i + neighbor);
+            // Animate point position
+            point = 0.5 + 0.5 * sin(time + 6.2831 * point);
+            float dist = length(neighbor + point - f);
+            minDist = min(minDist, dist);
+        }
+    }
+
+    return minDist;
+}
+```
+
+## Distance Metrics
+
+```glsl
+float euclidean(vec2 v) { return length(v); }
+float manhattan(vec2 v) { return abs(v.x) + abs(v.y); }
+float chebyshev(vec2 v) { return max(abs(v.x), abs(v.y)); }
+```
+
+## Practical Applications
+
+```glsl
+// Cracked ground
+vec3 crackedGround(vec2 st) {
+    float edges = worleyEdges(st * 5.0);
+    return mix(vec3(0.1), vec3(0.5, 0.4, 0.3), smoothstep(0.0, 0.05, edges));
+}
+```