cokit-cli 1.3.0 → 1.4.0

package/skills/ck-git/references/workflow-push.md

@@ -0,0 +1,52 @@
+# Push Workflow
+
+Execute via `ck-git-manager` subagent.
+
+## Pre-Push Checklist
+1. All changes committed
+2. Secrets scanned (see `safety-protocols.md`)
+3. Branch pushed to remote
+
+## Tool 1: Verify State
+```bash
+git status && \
+git log origin/$(git rev-parse --abbrev-ref HEAD)..HEAD --oneline 2>/dev/null || echo "NO_UPSTREAM"
+```
+
+**If uncommitted changes:** Warn user, suggest commit first.
+**If NO_UPSTREAM:** Use `git push -u origin HEAD`.
+
+## Tool 2: Push
+```bash
+git push origin HEAD
+```
+
+**On success:** Report commit hashes pushed.
+
+## Error Handling
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `rejected - non-fast-forward` | Remote has newer commits | `git pull --rebase`, resolve conflicts, push again |
+| `no upstream branch` | Branch not tracked | `git push -u origin HEAD` |
+| `Authentication failed` | Invalid credentials | Check `gh auth status` or SSH keys |
+| `Repository not found` | Wrong remote URL | Verify `git remote -v` |
+| `Permission denied` | No write access | Check repository permissions |
+
+## Force Push (DANGER)
+
+**NEVER force push to main/master/production branches.**
+
+If user explicitly requests force push on feature branch:
+```bash
+git push -f origin HEAD
+```
+
+**Warn user:** "Force push rewrites history. Collaborators may lose work."
+
+## Output Format
+```
+✓ pushed: N commits to origin/{branch}
+  - abc123 feat(auth): add login
+  - def456 fix(api): resolve timeout
+```

package/skills/ck-mcp-management/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: ck-mcp-management
+description: Manage MCP servers - discover, analyze, execute tools/prompts/resources. Use for MCP integrations, intelligent tool selection, multi-server management, context-efficient capability discovery.
+argument-hint: "[task or server-name]"
+---
+
+# MCP Management
+
+Skill for managing and interacting with Model Context Protocol (MCP) servers.
+
+## Overview
+
+MCP is an open protocol enabling AI agents to connect to external tools and data sources. This skill provides scripts and utilities to discover, analyze, and execute MCP capabilities from configured servers without polluting the main context window.
+
+**Key Benefits**:
+- Progressive disclosure of MCP capabilities (load only what's needed)
+- Intelligent tool/prompt/resource selection based on task requirements
+- Multi-server management from single config file
+- Context-efficient: subagents handle MCP discovery and execution
+- Persistent tool catalog: automatically saves discovered tools to JSON for fast reference
+
+## When to Use This Skill
+
+Use this skill when:
+1. **Discovering MCP Capabilities**: Need to list available tools/prompts/resources from configured servers
+2. **Task-Based Tool Selection**: Analyzing which MCP tools are relevant for a specific task
+3. **Executing MCP Tools**: Calling MCP tools programmatically with proper parameter handling
+4. **MCP Integration**: Building or debugging MCP client implementations
+5. **Context Management**: Avoiding context pollution by delegating MCP operations to subagents
+
+## Core Capabilities
+
+### 1. Configuration Management
+
+MCP servers configured in `.vscode/mcp.json`.
+
+**Gemini CLI Integration** (recommended): Create symlink to `.gemini/settings.json`:
+```bash
+mkdir -p .gemini && ln -sf .vscode/mcp.json .gemini/settings.json
+```
+
+See [references/configuration.md](references/configuration.md) and [references/gemini-cli-integration.md](references/gemini-cli-integration.md).
+
+**GEMINI.md Response Format**: Project root contains `GEMINI.md` that Gemini CLI auto-loads, enforcing structured JSON responses:
+```json
+{"server":"name","tool":"name","success":true,"result":<data>,"error":null}
+```
+
+This ensures parseable, consistent output instead of unpredictable natural language. The file defines:
+- Mandatory JSON-only response format (no markdown, no explanations)
+- Maximum 500 character responses
+- Error handling structure
+- Available MCP servers reference
+
+**Benefits**: Programmatically parseable output, consistent error reporting, DRY configuration (format defined once), context-efficient (auto-loaded by Gemini CLI).
+
+### 2. Capability Discovery
+
+```bash
+npx tsx scripts/cli.ts list-tools  # Saves to assets/tools.json
+npx tsx scripts/cli.ts list-prompts
+npx tsx scripts/cli.ts list-resources
+```
+
+Aggregates capabilities from multiple servers with server identification.
+
+### 3. Intelligent Tool Analysis
+
+LLM analyzes `assets/tools.json` directly - better than keyword matching algorithms.
+
+### 4. Tool Execution
+
+**Primary: Gemini CLI** (if available)
+```bash
+# IMPORTANT: Use stdin piping, NOT -p flag (deprecated, skips MCP init)
+echo "Take a screenshot of https://example.com" | gemini -y -m <gemini.model>
+```
+
+**Secondary: Direct Scripts**
+```bash
+npx tsx scripts/cli.ts call-tool memory create_entities '{"entities":[...]}'
+```
+
+**Fallback: mcp-manager Subagent**
+
+See [references/gemini-cli-integration.md](references/gemini-cli-integration.md) for complete examples.
+
+## Implementation Patterns
+
+### Pattern 1: Gemini CLI Auto-Execution (Primary)
+
+Use Gemini CLI for automatic tool discovery and execution. Gemini CLI auto-loads `GEMINI.md` from project root to enforce structured JSON responses.
+
+**Quick Example**:
+```bash
+# IMPORTANT: Use stdin piping, NOT -p flag (deprecated, skips MCP init)
+# Add "Return JSON only per GEMINI.md instructions" to enforce structured output
+echo "Take a screenshot of https://example.com. Return JSON only per GEMINI.md instructions." | gemini -y -m <gemini.model>
+```
+
+**Expected Output**:
+```json
+{"server":"puppeteer","tool":"screenshot","success":true,"result":"screenshot.png","error":null}
+```
+
+**Benefits**:
+- Automatic tool discovery
+- Structured JSON responses (parseable by AI)
+- GEMINI.md auto-loaded for consistent formatting
+- Faster than subagent orchestration
+- No natural language ambiguity
+
+See [references/gemini-cli-integration.md](references/gemini-cli-integration.md) for complete guide.
+
+### Pattern 2: Subagent-Based Execution (Fallback)
+
+Use `mcp-manager` agent when Gemini CLI unavailable. Subagent discovers tools, selects relevant ones, executes tasks, reports back.
+
+**Benefit**: Main context stays clean, only relevant tool definitions loaded when needed.
+
+### Pattern 3: LLM-Driven Tool Selection
+
+LLM reads `assets/tools.json`, intelligently selects relevant tools using context understanding, synonyms, and intent recognition.
+
+### Pattern 4: Multi-Server Orchestration
+
+Coordinate tools across multiple servers. Each tool knows its source server for proper routing.
+
+## Scripts Reference
+
+### scripts/mcp-client.ts
+
+Core MCP client manager class. Handles:
+- Config loading from `.vscode/mcp.json`
+- Connecting to multiple MCP servers
+- Listing tools/prompts/resources across all servers
+- Executing tools with proper error handling
+- Connection lifecycle management
+
+### scripts/cli.ts
+
+Command-line interface for MCP operations. Commands:
+- `list-tools` - Display all tools and save to `assets/tools.json`
+- `list-prompts` - Display all prompts
+- `list-resources` - Display all resources
+- `call-tool <server> <tool> <json>` - Execute a tool
+
+**Note**: `list-tools` persists complete tool catalog to `assets/tools.json` with full schemas for fast reference, offline browsing, and version control.
+
+## Quick Start
+
+**Method 1: Gemini CLI** (recommended)
+```bash
+npm install -g gemini-cli
+mkdir -p .gemini && ln -sf .vscode/mcp.json .gemini/settings.json
+# IMPORTANT: Use stdin piping, NOT -p flag (deprecated, skips MCP init)
+# GEMINI.md auto-loads to enforce JSON responses
+echo "Take a screenshot of https://example.com. Return JSON only per GEMINI.md instructions." | gemini -y -m <gemini.model>
+```
+
+Returns structured JSON: `{"server":"puppeteer","tool":"screenshot","success":true,"result":"screenshot.png","error":null}`
+
+**Method 2: Scripts**
+```bash
+cd skills/mcp-management/scripts && npm install
+npx tsx cli.ts list-tools  # Saves to assets/tools.json
+npx tsx cli.ts call-tool memory create_entities '{"entities":[...]}'
+```
+
+**Method 3: mcp-manager Subagent**
+
+See [references/gemini-cli-integration.md](references/gemini-cli-integration.md) for complete guide.
+
+## Technical Details
+
+See [references/mcp-protocol.md](references/mcp-protocol.md) for:
+- JSON-RPC protocol details
+- Message types and formats
+- Error codes and handling
+- Transport mechanisms (stdio, HTTP+SSE)
+- Best practices
+
+## Integration Strategy
+
+### Execution Priority
+
+1. **Gemini CLI** (Primary): Fast, automatic, intelligent tool selection
+   - Check: `command -v gemini`
+   - Execute: `echo "<task>" | gemini -y -m <gemini.model>`
+   - **IMPORTANT**: Use stdin piping, NOT `-p` flag (deprecated, skips MCP init)
+   - Best for: All tasks when available
+
+2. **Direct CLI Scripts** (Secondary): Manual tool specification
+   - Use when: Need specific tool/server control
+   - Execute: `npx tsx scripts/cli.ts call-tool <server> <tool> <args>`
+
+3. **mcp-manager Subagent** (Fallback): Context-efficient delegation
+   - Use when: Gemini unavailable or failed
+   - Keeps main context clean
+
+### Integration with Agents
+
+The `mcp-manager` agent uses this skill to:
+- Check Gemini CLI availability first
+- Execute via `gemini` command if available
+- Fallback to direct script execution
+- Discover MCP capabilities without loading into main context
+- Report results back to main agent
+
+This keeps main agent context clean and enables efficient MCP integration.

package/skills/ck-mermaidjs-v11/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: ck-mermaidjs-v11
+description: Create diagrams with Mermaid.js v11 syntax. Use for flowcharts, sequence diagrams, class diagrams, ER diagrams, Gantt charts, state diagrams, architecture diagrams, timelines, user journeys.
+argument-hint: "[diagram-type or description]"
+---
+
+# Mermaid.js v11
+
+## Overview
+
+Create text-based diagrams using Mermaid.js v11 declarative syntax. Convert code to SVG/PNG/PDF via CLI or render in browsers/markdown files.
+
+## Quick Start
+
+**Basic Diagram Structure:**
+```
+{diagram-type}
+  {diagram-content}
+```
+
+**Common Diagram Types:**
+- `flowchart` - Process flows, decision trees
+- `sequenceDiagram` - Actor interactions, API flows
+- `classDiagram` - OOP structures, data models
+- `stateDiagram` - State machines, workflows
+- `erDiagram` - Database relationships
+- `gantt` - Project timelines
+- `journey` - User experience flows
+
+See `references/diagram-types.md` for all 24+ types with syntax.
+
+## Creating Diagrams
+
+**Inline Markdown Code Blocks:**
+````markdown
+```mermaid
+flowchart TD
+    A[Start] --> B{Decision}
+    B -->|Yes| C[Action]
+    B -->|No| D[End]
+```
+````
+
+**Configuration via Frontmatter:**
+````markdown
+```mermaid
+---
+theme: dark
+---
+flowchart LR
+    A --> B
+```
+````
+
+**Comments:** Use `%% ` prefix for single-line comments.
+
+## CLI Usage
+
+Convert `.mmd` files to images:
+```bash
+# Installation
+npm install -g @mermaid-js/mermaid-cli
+
+# Basic conversion
+mmdc -i diagram.mmd -o diagram.svg
+
+# With theme and background
+mmdc -i input.mmd -o output.png -t dark -b transparent
+
+# Custom styling
+mmdc -i diagram.mmd --cssFile style.css -o output.svg
+```
+
+See `references/cli-usage.md` for Docker, batch processing, and advanced workflows.
+
+## JavaScript Integration
+
+**HTML Embedding:**
+```html
+<pre class="mermaid">
+  flowchart TD
+    A[Client] --> B[Server]
+</pre>
+<script src="https://cdn.jsdelivr.net/npm/mermaid@latest/dist/mermaid.min.js"></script>
+<script>mermaid.initialize({ startOnLoad: true });</script>
+```
+
+See `references/integration.md` for Node.js API and advanced integration patterns.
+
+## Configuration & Theming
+
+**Common Options:**
+- `theme`: "default", "dark", "forest", "neutral", "base"
+- `look`: "classic", "handDrawn"
+- `fontFamily`: Custom font specification
+- `securityLevel`: "strict", "loose", "antiscript"
+
+See `references/configuration.md` for complete config options, theming, and customization.
+
+## Practical Patterns
+
+Load `references/examples.md` for:
+- Architecture diagrams
+- API documentation flows
+- Database schemas
+- Project timelines
+- State machines
+- User journey maps
+
+## Resources
+
+- `references/diagram-types.md` - Syntax for all 24+ diagram types
+- `references/configuration.md` - Config, theming, accessibility
+- `references/cli-usage.md` - CLI commands and workflows
+- `references/integration.md` - JavaScript API and embedding
+- `references/examples.md` - Practical patterns and use cases

package/skills/ck-planning/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: ck-plan
+description: "Plan implementations, design architectures, create technical roadmaps with detailed phases. Use for feature planning, system design, solution architecture, implementation strategy, phase documentation."
+argument-hint: "[task] OR [archive|red-team|validate]"
+license: MIT
+---
+
+# Planning
+
+Create detailed technical implementation plans through research, codebase analysis, solution design, and comprehensive documentation.
+
+**IMPORTANT:** Before you start, scan unfinished plans in the current project at `./plans/` directory, read the `plan.md`, if there are relevant plans with your upcoming plan, update them as well. If you're unsure or need more clarifications, use ask the user.
+
+### Cross-Plan Dependency Detection
+
+During the pre-creation scan, detect and mark blocking relationships between plans:
+
+1. **Scan** — Read `plan.md` frontmatter of each unfinished plan (status != `completed`/`cancelled`)
+2. **Compare scope** — Check overlapping files, shared dependencies, same feature area
+3. **Classify relationship:**
+   - New plan needs output of existing plan → new plan `blockedBy: [existing-plan-dir]`
+   - New plan changes something existing plan depends on → existing plan `blockedBy: [new-plan-dir]`, new plan `blocks: [existing-plan-dir]`
+   - Mutual dependency → both plans reference each other in `blockedBy`/`blocks`
+4. **Bidirectional update** — When relationship detected, update BOTH `plan.md` files' frontmatter
+5. **Ambiguous?** → Use asking the user with header "Plan Dependency", present detected overlap, ask user to confirm relationship type (blocks/blockedBy/none)
+
+**Frontmatter fields** (relative plan dir paths):
+```yaml
+blockedBy: [260301-1200-auth-system]     # This plan waits on these plans
+blocks: [260228-0900-user-dashboard]     # This plan blocks these plans
+```
+
+**Status interaction:** A plan with `blockedBy` entries where ANY blocker is not `completed` → plan status should note `blocked` in its overview. When all blockers complete, the blocked plan becomes unblocked automatically on next scan.
+
+## Default (No Arguments)
+
+If invoked with a task description, proceed with planning workflow. If invoked WITHOUT arguments or with unclear intent, use asking the user to present available operations:
+
+| Operation | Description |
+|-----------|-------------|
+| `(default)` | Create implementation plan for a task |
+| `archive` | Write journal entry & archive plans |
+| `red-team` | Adversarial plan review |
+| `validate` | Critical questions interview |
+
+Present as options by asking the user with header "Planning Operation", question "What would you like to do?".
+
+## Workflow Modes
+
+Default: `--auto` (analyze task complexity and auto-pick mode).
+
+| Flag | Mode | Research | Red Team | Validation | Cook Flag |
+|------|------|----------|----------|------------|-----------|
+| `--auto` | Auto-detect | Follows mode | Follows mode | Follows mode | Follows mode |
+| `--fast` | Fast | Skip | Skip | Skip | `--auto` |
+| `--hard` | Hard | 2 researchers | Yes | Optional | (none) |
+| `--parallel` | Parallel | 2 researchers | Yes | Optional | `--parallel` |
+| `--two` | Two approaches | 2+ researchers | After selection | After selection | (none) |
+
+Add `--no-tasks` to skip task hydration in any mode.
+
+Load: `references/workflow-modes.md` for auto-detection logic, per-mode workflows, context reminders.
+
+## When to Use
+
+- Planning new feature implementations
+- Architecting system designs
+- Evaluating technical approaches
+- Creating implementation roadmaps
+- Breaking down complex requirements
+
+## Core Responsibilities & Rules
+
+Always honoring **YAGNI**, **KISS**, and **DRY** principles.
+**Be honest, be brutal, straight to the point, and be concise.**
+
+### 0. Scope Challenge
+Load: `references/scope-challenge.md`
+**Skip if:** `--fast` mode or trivial task (single file fix, <20 word description)
+
+### 1. Research & Analysis
+Load: `references/research-phase.md`
+**Skip if:** Fast mode or provided with researcher reports
+
+### 2. Codebase Understanding
+Load: `references/codebase-understanding.md`
+**Skip if:** Provided with scout reports
+
+### 3. Solution Design
+Load: `references/solution-design.md`
+
+### 4. Plan Creation & Organization
+Load: `references/plan-organization.md`
+
+### 5. Task Breakdown & Output Standards
+Load: `references/output-standards.md`
+
+## Process Flow (Authoritative)
+
+```mermaid
+flowchart TD
+    A[Pre-Creation Check] --> B[Cross-Plan Scan]
+    B --> C[Scope Challenge]
+    C --> D[Mode Detection]
+    D -->|fast| E[Skip Research]
+    D -->|hard/parallel/two| F[Spawn Researchers]
+    E --> G[Codebase Analysis]
+    F --> G
+    G --> H[Write Plan via Planner]
+    H --> I{Red Team?}
+    I -->|Yes| J[Red Team Review]
+    I -->|No| K{Validate?}
+    J --> K
+    K -->|Yes| L[Validation Interview]
+    K -->|No| M[Hydrate Tasks]
+    L --> M
+    M --> N[Output Cook Command]
+    N --> O[Journal]
+```
+
+**This diagram is the authoritative workflow.** Prose sections below provide detail for each node.
+
+## Workflow Process
+
+1. **Pre-Creation Check** → Check Plan Context for active/suggested/none
+1b. **Cross-Plan Scan** → Scan unfinished plans, detect `blockedBy`/`blocks` relationships, update both plans
+1c. **Scope Challenge** → Run Step 0 scope questions, select mode (see `references/scope-challenge.md`)
+    **Skip if:** `--fast` mode or trivial task
+2. **Mode Detection** → Auto-detect or use explicit flag (see `workflow-modes.md`)
+3. **Research Phase** → Spawn researchers (skip in fast mode)
+4. **Codebase Analysis** → Read docs, scout if needed
+5. **Plan Documentation** → Write comprehensive plan via planner subagent
+6. **Red Team Review** → Run `/ck-plan red-team {plan-path}` (hard/parallel/two modes)
+7. **Post-Plan Validation** → Run `/ck-plan validate {plan-path}` (hard/parallel/two modes)
+8. **Hydrate Tasks** → Create Tasks from phases (default on, `--no-tasks` to skip)
+9. **Context Reminder** → Output cook command with absolute path (MANDATORY)
+10. **Journal** → Run `/ck-journal` to write a concise technical journal entry upon completion
+
+## Output Requirements
+**IMPORTANT:** Invoke "/ck-project-organization" skill to organize the outputs.
+
+- DO NOT implement code - only create plans
+- Respond with plan file path and summary
+- Ensure self-contained plans with necessary context
+- Include code snippets/pseudocode when clarifying
+- Fully respect the `./docs/development-rules.md` file
+
+## Task Management
+
+Plan files = persistent. Tasks = session-scoped. Hydration bridges the gap.
+
+**Default:** Auto-hydrate tasks after plan files are written. Skip with `--no-tasks`.
+**3-Task Rule:** <3 phases → skip task creation.
+**Fallback:** Task tools (`TaskCreate`/`TaskUpdate`/`TaskGet`/`TaskList`) are CLI-only — unavailable in VSCode extension. If they error, use `TodoWrite` for tracking. Plan files remain the source of truth; hydration is an optimization, not a requirement.
+
+Load: `references/task-management.md` for hydration pattern, TaskCreate patterns, cook handoff protocol.
+
+### Hydration Workflow
+1. Write plan.md + phase files (persistent layer)
+2. TaskCreate per phase with `addBlockedBy` chain (skip if Task tools unavailable)
+3. TaskCreate for critical/high-risk steps within phases (skip if Task tools unavailable)
+4. Metadata: phase, priority, effort, planDir, phaseFile
+5. Cook picks up via TaskList (same session) or re-hydrates (new session)
+
+## Active Plan State
+
+Check `## Plan Context` injected by hooks:
+- **"Plan: {path}"** → Active plan. Ask "Continue? [Y/n]"
+- **"Suggested: {path}"** → Branch hint only. Ask if activate or create new.
+- **"Plan: none"** → Create new using `Plan dir:` from `## Naming`
+
+Reports: Active plans → plan-specific path. Suggested → default path.
+
+### Important
+**DO NOT** create plans or reports in USER directory.
+**MUST** create plans or reports in **THE CURRENT WORKING PROJECT DIRECTORY**.
+
+## Subcommands
+
+| Subcommand | Reference | Purpose |
+|------------|-----------|---------|
+| `/ck-plan archive` | `references/archive-workflow.md` | Archive plans + write journal entries |
+| `/ck-plan red-team` | `references/red-team-workflow.md` | Adversarial plan review with hostile reviewers |
+| `/ck-plan validate` | `references/validate-workflow.md` | Validate plan with critical questions interview |
+
+## Quality Standards
+
+- Thorough and specific, consider long-term maintainability
+- Research thoroughly when uncertain
+- Address security and performance concerns
+- Detailed enough for junior developers
+- Validate against existing codebase patterns
+
+**Remember:** Plan quality determines implementation success. Be comprehensive and consider all solution aspects.

package/skills/ck-planning/references/research-phase.md

@@ -0,0 +1,49 @@
+# Research & Analysis Phase
+
+**When to skip:** If provided with researcher reports, skip this phase.
+
+## Core Activities
+
+### Parallel Researcher Agents
+- Spawn multiple `ck-researcher` agents in parallel to investigate different approaches
+- Wait for all researcher agents to report back before proceeding
+- Each researcher investigates a specific aspect or approach
+
+### Sequential Thinking
+- Use `ck-sequential-thinking` skill for dynamic and reflective problem-solving
+- Structured thinking process for complex analysis
+- Enables multi-step reasoning with revision capability
+
+### Documentation Research
+- Use `docs-seeker` skill to read and understand documentation
+- Research plugins, packages, and frameworks
+- Find latest technical documentation using llms.txt standard
+
+### GitHub Analysis
+- Use `gh` command to read and analyze:
+  - GitHub Actions logs
+  - Pull requests
+  - Issues and discussions
+- Extract relevant technical context from GitHub resources
+
+### Remote Repository Analysis
+When given GitHub repository URL, generate fresh codebase summary:
+```bash
+# usage: 
+repomix --remote <github-repo-url>
+# example: 
+repomix --remote https://github.com/mrgoonie/human-mcp
+```
+
+### Debugger Delegation
+- Delegate to `ck-debugger` agent for root cause analysis
+- Use when investigating complex issues or bugs
+- Debugger agent specializes in diagnostic tasks
+
+## Best Practices
+
+- Research breadth before depth
+- Document findings for synthesis phase
+- Identify multiple approaches for comparison
+- Consider edge cases during research
+- Note security implications early