cokit-cli 1.2.7 → 1.4.0

package/templates/repo/.github/skills/ck-research/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: ck-research
+description: "Research technical solutions, analyze architectures, gather requirements thoroughly. Use for technology evaluation, best practices research, solution design, scalability/security/maintainability analysis."
+license: MIT
+argument-hint: "[topic]"
+---
+
+# Research
+
+## Research Methodology
+
+Always honoring **YAGNI**, **KISS**, and **DRY** principles.
+**Be honest, be brutal, straight to the point, and be concise.**
+
+### Phase 1: Scope Definition
+
+First, you will clearly define the research scope by:
+- Identifying key terms and concepts to investigate
+- Determining the recency requirements (how current must information be)
+- Establishing evaluation criteria for sources
+- Setting boundaries for the research depth
+
+### Phase 2: Systematic Information Gathering
+
+You will employ a multi-source research strategy:
+
+1. **Search Strategy**:
+   - **Gemini Toggle**: Check `.ck.json` (or `.ck.json`) for `skills.research.useGemini` (default: `true`). If `false`, skip Gemini and use WebSearch.
+   - **Gemini Model**: Read from `.ck.json`: `gemini.model` (default: `gemini-3-flash-preview`)
+   - If `useGemini` is enabled and `gemini` bash command is available, execute `gemini -y -m <gemini.model> "...your search prompt..."` bash command (timeout: 10 minutes) and save the output using `Report:` path from `## Naming` section (including all citations).
+   - If `useGemini` is disabled or `gemini` bash command is not available, use `WebSearch` tool.
+   - Run multiple `gemini` bash commands or `WebSearch` tools in parallel to search for relevant information.
+   - Craft precise search queries with relevant keywords
+   - Include terms like "best practices", "2024", "latest", "security", "performance"
+   - Search for official documentation, GitHub repositories, and authoritative blogs
+   - Prioritize results from recognized authorities (official docs, major tech companies, respected developers)
+   - **IMPORTANT:** You are allowed to perform at most **5 researches (max 5 tool calls)**, user might request less than this amount, **strictly respect it**, think carefully based on the task before performing each related research topic.
+
+2. **Deep Content Analysis**:
+   - When you found a potential Github repository URL, use `docs-seeker` skill to find read it.
+   - Focus on official documentation, API references, and technical specifications
+   - Analyze README files from popular GitHub repositories
+   - Review changelog and release notes for version-specific information
+
+3. **Video Content Research**:
+   - Prioritize content from official channels, recognized experts, and major conferences
+   - Focus on practical demonstrations and real-world implementations
+
+4. **Cross-Reference Validation**:
+   - Verify information across multiple independent sources
+   - Check publication dates to ensure currency
+   - Identify consensus vs. controversial approaches
+   - Note any conflicting information or debates in the community
+
+### Phase 3: Analysis and Synthesis
+
+You will analyze gathered information by:
+- Identifying common patterns and best practices
+- Evaluating pros and cons of different approaches
+- Assessing maturity and stability of technologies
+- Recognizing security implications and performance considerations
+- Determining compatibility and integration requirements
+
+### Phase 4: Report Generation
+
+**Notes:**
+- Research reports are saved using `Report:` path from `## Naming` section.
+- If `## Naming` section is not available, ask main agent to provide the output path.
+
+You will create a comprehensive markdown report with the following structure:
+
+```markdown
+# Research Report: [Topic]
+
+## Executive Summary
+[2-3 paragraph overview of key findings and recommendations]
+
+## Research Methodology
+- Sources consulted: [number]
+- Date range of materials: [earliest to most recent]
+- Key search terms used: [list]
+
+## Key Findings
+
+### 1. Technology Overview
+[Comprehensive description of the technology/topic]
+
+### 2. Current State & Trends
+[Latest developments, version information, adoption trends]
+
+### 3. Best Practices
+[Detailed list of recommended practices with explanations]
+
+### 4. Security Considerations
+[Security implications, vulnerabilities, and mitigation strategies]
+
+### 5. Performance Insights
+[Performance characteristics, optimization techniques, benchmarks]
+
+## Comparative Analysis
+[If applicable, comparison of different solutions/approaches]
+
+## Implementation Recommendations
+
+### Quick Start Guide
+[Step-by-step getting started instructions]
+
+### Code Examples
+[Relevant code snippets with explanations]
+
+### Common Pitfalls
+[Mistakes to avoid and their solutions]
+
+## Resources & References
+
+### Official Documentation
+- [Linked list of official docs]
+
+### Recommended Tutorials
+- [Curated list with descriptions]
+
+### Community Resources
+- [Forums, Discord servers, Stack Overflow tags]
+
+### Further Reading
+- [Advanced topics and deep dives]
+
+## Appendices
+
+### A. Glossary
+[Technical terms and definitions]
+
+### B. Version Compatibility Matrix
+[If applicable]
+
+### C. Raw Research Notes
+[Optional: detailed notes from research process]
+```
+
+## Quality Standards
+
+You will ensure all research meets these criteria:
+- **Accuracy**: Information is verified across multiple sources
+- **Currency**: Prioritize information from the last 12 months unless historical context is needed
+- **Completeness**: Cover all aspects requested by the user
+- **Actionability**: Provide practical, implementable recommendations
+- **Clarity**: Use clear language, define technical terms, provide examples
+- **Attribution**: Always cite sources and provide links for verification
+
+## Special Considerations
+
+- When researching security topics, always check for recent CVEs and security advisories
+- For performance-related research, look for benchmarks and real-world case studies
+- When investigating new technologies, assess community adoption and support levels
+- For API documentation, verify endpoint availability and authentication requirements
+- Always note deprecation warnings and migration paths for older technologies
+
+## Output Requirements
+**IMPORTANT:** Invoke "/ck-project-organization" skill to organize the outputs.
+
+Your final report must:
+1. Be saved using the `Report:` path from `## Naming` section with a descriptive filename
+2. Include a timestamp of when the research was conducted
+3. Provide clear section navigation with a table of contents for longer reports
+4. Use code blocks with appropriate syntax highlighting
+5. Include diagrams or architecture descriptions where helpful (in mermaid or ASCII art)
+6. Conclude with specific, actionable next steps
+
+**IMPORTANT:** Sacrifice grammar for the sake of concision when writing reports.
+**IMPORTANT:** In reports, list any unresolved questions at the end, if any.
+
+**Remember:** You are not just collecting information, but providing strategic technical intelligence that enables informed decision-making. Your research should anticipate follow-up questions and provide comprehensive coverage of the topic while remaining focused and practical.

package/templates/repo/.github/skills/ck-scout/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: ck-scout
+description: "Fast codebase scouting using parallel agents. Use for file discovery, task context gathering, quick searches across directories. Supports internal (Explore) and external (Gemini/OpenCode) agents."
+argument-hint: "[search-target] [ext]"
+---
+
+# Scout
+
+Fast, token-efficient codebase scouting using parallel agents to find files needed for tasks.
+
+## Arguments
+- Default: Scout using built-in Explore subagents in parallel (`./references/internal-scouting.md`)
+- `ext`: Scout using external Gemini/OpenCode CLI tools in parallel (`./references/external-scouting.md`)
+
+## When to Use
+
+- Beginning work on feature spanning multiple directories
+- User mentions needing to "find", "locate", or "search for" files
+- Starting debugging session requiring file relationships understanding
+- User asks about project structure or where functionality lives
+- Before changes that might affect multiple codebase parts
+
+## Quick Start
+
+1. Analyze user prompt to identify search targets
+2. Use a wide range of Grep and Glob patterns to find relevant files and estimate scale of the codebase
+3. Spawn parallel agents with divided directories
+4. Collect results into concise report
+
+## Configuration
+
+Read from `.ck.json`:
+- `gemini.model` - Gemini model (default: `gemini-3-flash-preview`)
+
+## Workflow
+
+### 1. Analyze Task
+- Parse user prompt for search targets
+- Identify key directories, patterns, file types, lines of code
+- Determine optimal SCALE value of subagents to spawn
+
+### 2. Divide and Conquer
+- Split codebase into logical segments per agent
+- Assign each agent specific directories or patterns
+- Ensure no overlap, maximize coverage
+
+### 3. Register Scout Tasks
+- **Skip if:** Agent count ≤ 2 (overhead exceeds benefit)
+- **Skip if:** Task tools unavailable (VSCode extension) — use `TodoWrite` instead
+- `TaskList` first — check for existing scout tasks in session
+- If not found, `TaskCreate` per agent with scope metadata
+- See `references/task-management-scouting.md` for patterns and examples
+
+### 4. Spawn Parallel Agents
+Load appropriate reference based on decision tree:
+- **Internal (Default):** `references/internal-scouting.md` (Explore subagents)
+- **External:** `references/external-scouting.md` (Gemini/OpenCode)
+
+**Notes:**
+- `TaskUpdate` each task to `in_progress` before spawning its agent (skip if Task tools unavailable)
+- Prompt detailed instructions for each subagent with exact directories or files it should read
+- Remember that each subagent has less than 200K tokens of context window
+- Amount of subagents to-be-spawned depends on the current system resources available and amount of files to be scanned
+- Each subagent must return a detailed summary report to a main agent
+
+### 5. Collect Results
+**IMPORTANT:** Invoke "/ck-project-organization" skill to organize the outputs.
+
+- Timeout: 3 minutes per agent (skip non-responders)
+- `TaskUpdate` completed tasks; log timed-out agents in report (skip if Task tools unavailable)
+- Aggregate findings into single report
+- List unresolved questions at end
+
+## Report Format
+
+```markdown
+# Scout Report
+
+## Relevant Files
+- `path/to/file.ts` - Brief description
+- ...
+
+## Unresolved Questions
+- Any gaps in findings
+```
+
+## References
+
+- `references/internal-scouting.md` - Using Explore subagents
+- `references/external-scouting.md` - Using Gemini/OpenCode CLI
+- `references/task-management-scouting.md` - Task patterns for scout coordination

package/templates/repo/.github/skills/ck-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 `.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/repo/.github/skills/ck-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/repo/.github/skills/ck-scout/references/task-management-scouting.md

@@ -0,0 +1,125 @@
+# Scout Task Management Patterns
+
+Track parallel scout agent execution via 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.