cokit-cli 1.0.9 → 1.2.0

package/skills/research/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: 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
+---
+
+# 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 `$HOME/.copilot/.ck.json` (or `~/.copilot/.ck.json`) for `skills.research.useGemini` (default: `true`). If `false`, skip Gemini and use WebSearch.
+   - **Gemini Model**: Read from `$HOME/.copilot/.ck.json`: `gemini.model` (default: `gemini-3.0-flash`)
+   - 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
+
+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/skills/scout/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: 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.
+version: 1.0.0
+---
+
+# 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 `$HOME/.copilot/.ck.json`:
+- `gemini.model` - Gemini model (default: `gemini-3.0-flash`)
+
+## 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. 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:**
+- 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
+
+### 4. Collect Results
+- Timeout: 3 minutes per agent (skip non-responders)
+- 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

package/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 `$HOME/.copilot/.ck.json`:
+```json
+{
+  "gemini": {
+    "model": "gemini-3.0-flash"
+  }
+}
+```
+
+Default model: `gemini-3.0-flash`
+
+## Gemini CLI (SCALE <= 3)
+
+### Command
+```bash
+gemini -y -m <model> "[prompt]"
+```
+
+### Example
+```bash
+gemini -y -m gemini-3.0-flash "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.0-flash '[prompt1]'"
+Task 2: subagent_type="Bash", prompt="Run: gemini -y -m gemini-3.0-flash '[prompt2]'"
+Task 3: subagent_type="Bash", prompt="Run: gemini -y -m gemini-3.0-flash '[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.0-flash 'Search db/, migrations/ for migration files'"
+Task 2 (Bash): "Run: gemini -y -m gemini-3.0-flash 'Search lib/, src/ for database schema files'"
+Task 3 (Bash): "Run: gemini -y -m gemini-3.0-flash '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/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/skills/{ck-sequential-thinking → sequential-thinking}/.env.example

@@ -1,8 +1,8 @@
-# Sequential Thinking Configuration
-
-# Disable thought logging output (useful for automated processing)
-# Set to "true" to disable console logging
-DISABLE_THOUGHT_LOGGING=false
-
-# History file location (optional, defaults to scripts/.thought-history.json)
-# THOUGHT_HISTORY_FILE=/path/to/custom/history.json
+# Sequential Thinking Configuration
+
+# Disable thought logging output (useful for automated processing)
+# Set to "true" to disable console logging
+DISABLE_THOUGHT_LOGGING=false
+
+# History file location (optional, defaults to scripts/.thought-history.json)
+# THOUGHT_HISTORY_FILE=/path/to/custom/history.json