cokit-cli 1.2.7 → 1.4.0

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/archive-workflow.md

@@ -0,0 +1,53 @@
+# Archive Workflow
+
+## Your mission
+Read and analyze the plans, then write journal entries and archive specific plans or all plans in the `plans` directory.
+
+## Plan Resolution
+1. If `$ARGUMENTS` provided → Use that path
+2. Else read all plans in the `plans` directory
+
+## Workflow
+
+### Step 1: Read Plan Files
+
+Read the plan directory:
+- `plan.md` - Overview and phases list
+- `phase-*.md` - 20 first lines of each phase file to understand the progress and status
+
+### Step 2: Summarize the plans and document them with `/ck-journal` skill invocation
+ask if user wants to document journal entries or not.
+Skip this step if user selects "No".
+If user selects "Yes":
+- Analyze the information in previous steps.
+- Use Task tool with `subagent_type="journal-writer"` in parallel to document all plans.
+- Journal entries should be concise and focused on the most important events, key changes, impacts, and decisions.
+- Keep journal entries in the `./docs/journals/` directory.
+
+### Step 3: Ask user to confirm the action before archiving these plans
+ask if user wants to proceed with archiving these plans, select specific plans to archive or all completed plans only.
+ask if user wants to delete permanently or move to the `./plans/archive` directory.
+
+### Step 4: Archive the plans
+Start archiving the plans based on the user's choice:
+- Move the plans to the `./plans/archive` directory.
+- Delete the plans permanently: `rm -rf ./plans/<plan-1> ./plans/<plan-2> ...`
+
+### Step 5: Ask if user wants to commit the changes
+ask if user wants to commit the changes with these options:
+- Stage and commit the changes (Use `/ck-git` for commit flow)
+- Commit and push the changes (Use `/ck-git` for push flow)
+- Nah, I'll do it later
+
+## Output
+After archiving the plans, provide summary:
+- Number of plans archived
+- Number of plans deleted permanently
+- Table of plans that are archived or deleted (title, status, created date, LOC)
+- Table of journal entries that are created (title, status, created date, LOC)
+
+## Important Notes
+- Only ask questions about genuine decision points
+- Sacrifice grammar for concision
+- List any unresolved questions at the end
+- Ensure token efficiency while maintaining high quality

package/skills/ck-planning/references/codebase-understanding.md

@@ -0,0 +1,62 @@
+# Codebase Understanding Phase
+
+**When to skip:** If provided with scout reports, skip this phase.
+
+## Core Activities
+
+### Parallel Scout Agents
+- Use `/ck-scout ext` (preferred) or `/ck-scout` (fallback) skill invocation to search the codebase for files needed to complete the task
+- Each scout locates files needed for specific task aspects
+- Wait for all scout agents to report back before analysis
+- Efficient for finding relevant code across large codebases
+
+### Essential Documentation Review
+ALWAYS read these files first:
+
+1. **`./docs/development-rules.md`** (IMPORTANT)
+   - File Name Conventions
+   - File Size Management
+   - Development rules and best practices
+   - Code quality standards
+   - Security guidelines
+
+2. **`./docs/codebase-summary.md`**
+   - Project structure and current status
+   - High-level architecture overview
+   - Component relationships
+
+3. **`./docs/code-standards.md`**
+   - Coding conventions and standards
+   - Language-specific patterns
+   - Naming conventions
+
+4. **`./docs/design-guidelines.md`** (if exists)
+   - Design system guidelines
+   - Branding and UI/UX conventions
+   - Component library usage
+
+### Environment Analysis
+- Review development environment setup
+- Analyze dotenv files and configuration
+- Identify required dependencies
+- Understand build and deployment processes
+
+### Pattern Recognition
+- Study existing patterns in codebase
+- Identify conventions and architectural decisions
+- Note consistency in implementation approaches
+- Understand error handling patterns
+
+### Integration Planning
+- Identify how new features integrate with existing architecture
+- Map dependencies between components
+- Understand data flow and state management
+- Consider backward compatibility
+
+## Best Practices
+
+- Start with documentation before diving into code
+- Use scouts for targeted file discovery
+- Document patterns found for consistency
+- Note any inconsistencies or technical debt
+- Consider impact on existing features

package/skills/ck-planning/references/output-standards.md

@@ -0,0 +1,145 @@
+# Output Standards & Quality
+
+## Plan File Format
+
+### YAML Frontmatter (Required for plan.md)
+
+All `plan.md` files MUST include YAML frontmatter at the top:
+
+```yaml
+---
+title: "{Brief plan title}"
+description: "{One-sentence summary for card preview}"
+status: pending  # pending | in-progress | completed | cancelled
+priority: P2     # P1 (High) | P2 (Medium) | P3 (Low)
+effort: 4h       # Estimated total effort
+issue: 74        # GitHub issue number (if applicable)
+branch: kai/feat/feature-name
+tags: [frontend, api]  # Category tags
+blockedBy: []    # Plan dirs this plan waits on (e.g., [260301-1200-auth-system])
+blocks: []       # Plan dirs this plan blocks (e.g., [260228-0900-user-dashboard])
+created: 2025-12-16
+---
+```
+
+### Auto-Population Rules
+
+When creating plans, auto-populate these fields:
+- **title**: Extract from task description
+- **description**: First sentence of Overview section
+- **status**: Always `pending` for new plans
+- **priority**: From user request or default `P2`
+- **effort**: Sum of phase estimates
+- **issue**: Parse from branch name or context
+- **branch**: Current git branch (`git branch --show-current`)
+- **tags**: Infer from task keywords (e.g., frontend, backend, api, auth)
+- **blockedBy**: Detected during pre-creation scan (empty `[]` if none)
+- **blocks**: Detected during pre-creation scan (empty `[]` if none)
+- **created**: Today's date in YYYY-MM-DD format
+
+### Tag Vocabulary (Recommended)
+
+Use these predefined tags for consistency:
+- **Type**: `feature`, `bugfix`, `refactor`, `docs`, `infra`
+- **Domain**: `frontend`, `backend`, `database`, `api`, `auth`
+- **Scope**: `critical`, `tech-debt`, `experimental`
+
+### Task Naming Conventions
+
+**subject** (imperative): Action verb + deliverable, <60 chars
+  Examples: "Setup database migrations", "Implement OAuth2 flow"
+
+**activeForm** (continuous): Present participle of subject
+  Examples: "Setting up database", "Implementing OAuth2"
+
+**description**: 1-2 sentences, concrete deliverables, reference phase file
+
+See `task-management.md` for full TaskCreate patterns and metadata.
+
+## Task Breakdown
+
+- Transform complex requirements into manageable, actionable tasks
+- Each task independently executable with clear dependencies
+- Prioritize by dependencies, risk, business value
+- Eliminate ambiguity in instructions
+- Include specific file paths for all modifications
+- Provide clear acceptance criteria per task
+
+### File Management
+
+List affected files with:
+- Full paths (not relative)
+- Action type (modify/create/delete)
+- Brief change description
+- Dependencies on other changes
+- Fully respect the `./docs/development-rules.md` file.
+
+## Workflow Process
+
+1. **Initial Analysis** → Read docs, understand context
+2. **Research Phase** → Spawn researchers in parallel, investigate approaches
+3. **Synthesis** → Analyze reports, identify optimal solution
+4. **Design Phase** → Create architecture, implementation design
+5. **Plan Documentation** → Write comprehensive plan in Markdown
+6. **Review & Refine** → Ensure completeness, clarity, actionability
+
+## Output Requirements
+
+### What Planners Do
+- Create plans ONLY (no implementation)
+- Provide plan file path and summary
+- Self-contained plans with necessary context
+- Code snippets/pseudocode when clarifying
+- Multiple options with trade-offs when appropriate
+- Fully respect the `./docs/development-rules.md` file.
+
+### Writing Style
+**IMPORTANT:** Sacrifice grammar for concision
+- Focus clarity over eloquence
+- Use bullets and lists
+- Short sentences
+- Remove unnecessary words
+- Prioritize actionable info
+
+### Unresolved Questions
+**IMPORTANT:** Use asking the user to ask users for unresolved questions at the end
+- Questions needing clarification
+- Technical decisions requiring input
+- Unknowns impacting implementation
+- Trade-offs requiring business decisions
+Revise the plan and phases based on the answers.
+
+## Quality Standards
+
+### Thoroughness
+- Thorough and specific in research/planning
+- Consider edge cases, failure modes
+- Think through entire user journey
+- Document all assumptions
+
+### Maintainability
+- Consider long-term maintainability
+- Design for future modifications
+- Document decision rationale
+- Avoid over-engineering
+- Fully respect the `./docs/development-rules.md` file.
+
+### Research Depth
+- When uncertain, research more
+- Multiple options with clear trade-offs
+- Validate against best practices
+- Consider industry standards
+
+### Security & Performance
+- Address all security concerns
+- Identify performance implications
+- Plan for scalability
+- Consider resource constraints
+
+### Implementability
+- Detailed enough for junior developers
+- Validate against existing patterns
+- Ensure codebase standards consistency
+- Provide clear examples
+
+**Remember:** Plan quality determines implementation success. Be comprehensive, consider all solution aspects.