cokit-cli 1.0.0 → 1.0.2

package/skills/ck-docs-seeker/workflows/library-search.md

@@ -0,0 +1,87 @@
+# General Library Documentation Search
+
+**Use when:** User asks about entire library/framework
+
+**Speed:** ⚡⚡ Moderate (30-60s)
+**Token usage:** 🟡 Medium
+**Accuracy:** 📚 Comprehensive
+
+## Trigger Patterns
+
+- "Documentation for [LIBRARY]"
+- "[LIBRARY] getting started"
+- "How to use [LIBRARY]"
+- "[LIBRARY] API reference"
+
+## Workflow (Script-First)
+
+```bash
+# STEP 1: Execute detect-topic.js script
+node scripts/detect-topic.js "<user query>"
+# Returns: {"isTopicSpecific": false} for general queries
+
+# STEP 2: Execute fetch-docs.js script (handles URL construction)
+node scripts/fetch-docs.js "<user query>"
+# Script constructs context7.com URL automatically
+# Script handles GitHub/website URL patterns
+# Returns: llms.txt content with 5-20+ URLs
+
+# STEP 3: Execute analyze-llms-txt.js script
+cat llms.txt | node scripts/analyze-llms-txt.js -
+# Groups URLs: critical, important, supplementary
+# Recommends: agent distribution strategy
+# Returns: {totalUrls, grouped, distribution}
+
+# STEP 4: Deploy agents based on script recommendation
+# - 1-3 URLs: Single agent or direct WebFetch
+# - 4-10 URLs: Deploy 3-5 Explorer agents
+# - 11+ URLs: Deploy 7 agents or phased approach
+
+# STEP 5: Aggregate and present
+# Synthesize findings: installation, concepts, API, examples
+```
+
+## Examples
+
+**Astro framework:**
+```bash
+# Execute scripts (no manual URL construction)
+node scripts/detect-topic.js "Documentation for Astro"
+# {"isTopicSpecific": false}
+
+node scripts/fetch-docs.js "Documentation for Astro"
+# Script fetches: context7.com/withastro/astro/llms.txt
+# Returns: llms.txt with 8 URLs
+
+node scripts/analyze-llms-txt.js < llms.txt
+# {totalUrls: 8, distribution: "3-agents", grouped: {...}}
+
+# Deploy 3 Explorer agents as recommended:
+# Agent 1: Getting started, installation, setup
+# Agent 2: Core concepts, components, layouts
+# Agent 3: Configuration, API reference
+
+# Aggregate and present comprehensive report
+```
+
+## Agent Distribution
+
+**1-3 URLs:** Single agent
+**4-10 URLs:** 3-5 agents (2-3 URLs each)
+**11-20 URLs:** 7 agents (balanced)
+**21+ URLs:** Two-phase (critical first, then important)
+
+## Known Libraries
+
+- Next.js: `vercel/next.js`
+- Astro: `withastro/astro`
+- Remix: `remix-run/remix`
+- shadcn/ui: `shadcn-ui/ui`
+- Better Auth: `better-auth/better-auth`
+
+## Fallback
+
+Scripts handle fallback automatically:
+1. `fetch-docs.js` tries context7.com
+2. If 404, script suggests WebSearch for llms.txt
+3. If still unavailable: [Repository Analysis](./repo-analysis.md)

package/skills/ck-docs-seeker/workflows/repo-analysis.md

@@ -0,0 +1,91 @@
+# Repository Analysis (No llms.txt)
+
+**Use when:** llms.txt not available on context7.com or official site
+
+**Speed:** ⚡⚡⚡ Slower (5-10min)
+**Token usage:** 🔴 High
+**Accuracy:** 🔍 Code-based
+
+## When to Use
+
+- Library not on context7.com
+- No llms.txt on official site
+- Need to analyze code structure
+- Documentation incomplete
+
+## Workflow
+
+```
+1. Find repository
+   → WebSearch: "[library] github repository"
+   → Verify: Official, active, has docs/
+
+2. Clone repository
+   → Bash: git clone [repo-url] /tmp/docs-analysis
+   → Optional: checkout specific version/tag
+
+3. Install Repomix (if needed)
+   → Bash: npm install -g repomix
+
+4. Pack repository
+   → Bash: cd /tmp/docs-analysis && repomix --output repomix-output.xml
+   → Repomix creates AI-friendly single file
+
+5. Read packed file
+   → Read: /tmp/docs-analysis/repomix-output.xml
+   → Extract: README, docs/, examples/, API files
+
+6. Analyze structure
+   → Identify: Documentation sections
+   → Extract: Installation, usage, API, examples
+   → Note: Code patterns, best practices
+
+7. Present findings
+   → Source: Repository analysis
+   → Caveat: Based on code, not official docs
+   → Include: Repository health (stars, activity)
+```
+
+## Example
+
+**Obscure library without llms.txt:**
+```bash
+# 1. Find
+WebSearch: "MyLibrary github repository"
+# Found: https://github.com/org/mylibrary
+
+# 2. Clone
+git clone https://github.com/org/mylibrary /tmp/docs-analysis
+
+# 3. Pack with Repomix
+cd /tmp/docs-analysis
+repomix --output repomix-output.xml
+
+# 4. Read
+Read: /tmp/docs-analysis/repomix-output.xml
+# Single XML file with entire codebase
+
+# 5. Extract documentation
+- README.md: Installation, overview
+- docs/: Usage guides, API reference
+- examples/: Code samples
+- src/: Implementation patterns
+
+# 6. Present
+Source: Repository analysis (no llms.txt)
+Health: 1.2K stars, active
+```
+
+## Repomix Benefits
+
+✅ Entire repo in single file
+✅ Preserves directory structure
+✅ AI-optimized format
+✅ Includes metadata
+
+## Alternative
+
+If no GitHub repo exists:
+→ Deploy multiple Researcher agents
+→ Gather: Official site, blog posts, tutorials, Stack Overflow
+→ Note: Quality varies, cross-reference sources

package/skills/ck-docs-seeker/workflows/topic-search.md

@@ -0,0 +1,77 @@
+# Topic-Specific Documentation Search
+
+**Use when:** User asks about specific feature/component/concept
+
+**Speed:** ⚡ Fastest (10-15s)
+**Token usage:** 🟢 Minimal
+**Accuracy:** 🎯 Highly targeted
+
+## Trigger Patterns
+
+- "How do I use [FEATURE] in [LIBRARY]?"
+- "[LIBRARY] [COMPONENT] documentation"
+- "Implement [FEATURE] with [LIBRARY]"
+- "[LIBRARY] [CONCEPT] guide"
+
+## Workflow (Script-First)
+
+```bash
+# STEP 1: Execute detect-topic.js script
+node scripts/detect-topic.js "<user query>"
+# Returns: {"topic": "X", "library": "Y", "isTopicSpecific": true}
+
+# STEP 2: Execute fetch-docs.js script (handles URL construction automatically)
+node scripts/fetch-docs.js "<user query>"
+# Script constructs: context7.com/{library}/llms.txt?topic={topic}
+# Script handles fallback if topic URL fails
+# Returns: llms.txt content with 1-5 URLs
+
+# STEP 3: Process results based on URL count
+# - 1-3 URLs: Read directly with WebFetch tool
+# - 4-5 URLs: Deploy 2-3 Explorer agents in parallel
+
+# STEP 4: Present findings
+# Focus on specific feature: installation, usage, examples
+```
+
+## Examples
+
+**shadcn date picker:**
+```bash
+# Execute script (automatic URL construction)
+node scripts/detect-topic.js "How do I use date picker in shadcn?"
+# {"topic": "date", "library": "shadcn/ui", "isTopicSpecific": true}
+
+node scripts/fetch-docs.js "How do I use date picker in shadcn?"
+# Script fetches: context7.com/shadcn-ui/ui/llms.txt?topic=date
+# Returns: 2-3 date-specific URLs
+
+# Read URLs directly with WebFetch
+# Present date picker documentation
+```
+
+**Next.js caching:**
+```bash
+# Execute scripts (no manual URL needed)
+node scripts/detect-topic.js "Next.js caching strategies"
+# {"topic": "cache", "library": "next.js", "isTopicSpecific": true}
+
+node scripts/fetch-docs.js "Next.js caching strategies"
+# Script fetches: context7.com/vercel/next.js/llms.txt?topic=cache
+# Returns: 3-4 URLs
+
+# Process URLs via 2 Explorer agents
+# Present caching strategies
+```
+
+## Benefits
+
+✅ 10x faster than full docs
+✅ No filtering needed
+✅ Minimal context load
+✅ Best user experience
+
+## Fallback
+
+If topic URL returns 404:
+→ Fallback to [General Library Search](./library-search.md)

package/skills/ck-frontend-design/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: 'ck-frontend-design'
+description: 'Create distinctive, production-grade frontend interfaces with high design quality. Use when building web components, pages, or applications, OR when provided screenshots/images/designs to replicate. Extracts design guidelines from screenshots, implements code following guidelines. Generates creative, polished code avoiding generic AI aesthetics.'
+---
+
+This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
+
+The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
+
+## Input Types & Workflows
+
+### When User Provides Screenshot/Image/Design Reference
+
+**MANDATORY workflow for screenshot/image/design inputs**:
+
+1. **Extract Design Guidelines** using `./references/design-extraction-overview.md`:
+   - Analyze screenshot/image visually
+   - Extract: colors (hex codes), typography (fonts, sizes, weights), spacing scale, layout patterns, visual hierarchy
+   - Document findings in project `docs/design-guidelines/extracted-design.md`
+   - See `./references/extraction-prompts.md` for comprehensive analysis prompts
+
+2. **Implement Code** following extracted guidelines:
+   - Use exact colors from extraction (hex codes)
+   - Match typography specifications (fonts, sizes, weights, line-heights)
+   - Replicate layout structure and spacing system
+   - Maintain visual hierarchy and component patterns
+   - Preserve aesthetic direction and mood
+
+3. **Verify Quality** using `./references/visual-analysis-overview.md`:
+   - Compare implementation to original screenshot
+   - Check color accuracy, spacing consistency, typography matching
+   - Ensure all design elements preserved
+
+**Important**: Do NOT skip to implementation. Extract design guidelines FIRST, then code.
+
+### When Building from Scratch (No Screenshot Provided)
+
+Follow "Design Thinking" process below to create original design.
+
+## Design Thinking
+
+Before coding, understand the context and commit to a BOLD aesthetic direction:
+- **Purpose**: What problem does this interface solve? Who uses it?
+- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
+- **Constraints**: Technical requirements (framework, performance, accessibility).
+- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
+
+**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.
+
+Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
+- Production-grade and functional
+- Visually striking and memorable
+- Cohesive with a clear aesthetic point-of-view
+- Meticulously refined in every detail
+
+## Frontend Aesthetics Guidelines
+
+Focus on:
+- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
+- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
+- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available (Use `anime.js` for animations: `./references/animejs.md`). Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
+- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
+- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
+
+### Analyzing Provided Screenshots/Images/Designs
+When user provides screenshots, photos, or design references to analyze or replicate, use `./references/design-extraction-overview.md` to extract design guidelines BEFORE implementation. This is MANDATORY for screenshot inputs (see "Input Types & Workflows" above).
+
+**Workflows**:
+- `./references/design-extraction-overview.md` - Extract guidelines from inspiration
+- `./references/visual-analysis-overview.md` - Analyze and verify quality
+- `./references/technical-overview.md` - Optimization and best practices
+
+NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
+
+Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
+
+**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
+
+Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.

package/skills/ck-frontend-design/references/analysis-best-practices.md

@@ -0,0 +1,80 @@
+# Analysis Best Practices
+
+Quality guidelines and common pitfalls.
+
+## Analysis Best Practices
+
+### 1. Be Specific
+❌ Generic: "Is this image good?"
+✓ Specific: "Does this align with brutalist aesthetic? Rate text overlay suitability."
+
+### 2. Use Structured Prompts
+Format analysis requests with numbered criteria for actionable feedback:
+```
+1. [Criterion A]
+2. [Criterion B]
+3. [Criterion C]
+Overall Rating: X/10
+```
+
+### 3. Request Hex Codes
+❌ Accept: "The image uses blue tones"
+✓ Demand: "Extract hex codes: #1E40AF, #3B82F6, #60A5FA"
+
+### 4. Compare Variations
+Never settle for the first generation without comparison:
+- Generate 3+ variations
+- Analyze comparatively
+- Select objectively based on scores
+
+### 5. Test Integration Context
+Analyze assets *with* UI elements overlaid, not in isolation:
+- Mock up text overlays
+- Test with actual buttons and CTAs
+- Evaluate in responsive contexts
+
+### 6. Document Decisions
+Save analysis reports for design system documentation:
+```
+docs/
+  assets/
+    hero-image.png
+    hero-analysis.md       # Analysis report
+    hero-color-palette.md  # Extracted colors
+  design-guidelines/
+    asset-usage.md         # Guidelines derived from analysis
+```
+
+## Common Analysis Pitfalls
+
+### ❌ Vague Feedback
+Analysis returns: "Colors are nice"
+**Fix**: Request specific hex codes and harmony evaluation
+
+### ❌ No Numeric Rating
+Analysis returns: "Pretty good quality"
+**Fix**: Always request 1-10 rating with justification
+
+### ❌ Missing Context
+Analyzing asset without specifying intended use
+**Fix**: Include context in prompt (hero section, background, marketing, etc.)
+
+### ❌ Single Analysis Point
+Only checking aesthetic, ignoring technical or integration concerns
+**Fix**: Use comprehensive evaluation template covering all dimensions
+
+## Evaluation Criteria
+
+### Core Evaluation Points
+- Visual coherence with chosen aesthetic direction
+- Color harmony and palette consistency
+- Composition balance and focal points
+- Typography compatibility (if text overlay needed)
+- Professional quality rating (1-10 scale)
+- Technical suitability (aspect ratio, resolution, file characteristics)
+
+### Context-Specific Points
+- **For hero sections**: Suitability for text overlay, visual hierarchy support
+- **For backgrounds**: Subtlety, pattern repetition quality, texture detail
+- **For marketing**: Brand alignment, emotional impact, attention-grabbing power
+- **For decorative elements**: Integration potential, visual weight, uniqueness

package/skills/ck-frontend-design/references/analysis-prompts.md

@@ -0,0 +1,141 @@
+# Analysis Prompt Templates
+
+Complete prompt templates for visual analysis and verification.
+
+## Comprehensive Analysis Prompt
+
+```
+Analyze this design asset comprehensively:
+
+## Design Alignment
+- Aesthetic Direction: [e.g., brutalist/minimalist/maximalist]
+- Expected Style: [describe target aesthetic]
+- Color Palette Target: [list expected colors]
+
+## Evaluation Criteria
+1. Visual Coherence: Does it match the intended aesthetic direction?
+2. Color Analysis: List dominant colors (hex codes). Evaluate harmony and mood.
+3. Composition: Analyze balance, focal points, negative space, visual flow.
+4. Typography Compatibility: Rate suitability for overlaying text (consider contrast, busy areas).
+5. Professional Quality: Rate 1-10 with justification.
+6. Technical Assessment: Resolution quality, compression artifacts, aspect ratio correctness.
+
+## Specific Feedback
+- What works well?
+- What specific elements need improvement?
+- What would elevate this to 9/10 quality?
+
+## Overall Rating: X/10
+Provide final score with clear reasoning.
+```
+
+## Comparison Analysis Prompt
+
+```
+Compare these 3 design variations:
+
+For each image, evaluate:
+1. Aesthetic alignment with [design direction]
+2. Color effectiveness
+3. Composition strength
+4. Text overlay suitability
+5. Professional quality rating (1-10)
+
+Then provide:
+- Ranking: Best to worst with justification
+- Recommendation: Which to use and why
+- Hybrid suggestion: Best elements from each to combine
+```
+
+## Color Extraction Prompt
+
+```
+Extract the complete color palette from this image:
+
+1. Identify 5-8 dominant colors with hex codes
+2. Classify each: primary, accent, neutral, or background
+3. Suggest CSS variable names (e.g., --color-primary-500)
+4. Evaluate color accessibility (WCAG contrast ratios)
+5. Recommend which colors work for text, backgrounds, accents
+
+Provide as structured data for easy CSS implementation.
+```
+
+## Integration Testing Prompt
+
+```
+Analyze this design asset with UI elements overlaid:
+
+1. Text Readability: Can all text be read clearly?
+2. Contrast Issues: Identify any WCAG violations
+3. Visual Hierarchy: Do buttons and CTAs stand out?
+4. Spacing Problems: Any crowding or poor breathing room?
+5. Responsive Concerns: Will this work on mobile at 9:16?
+
+Provide specific recommendations for adjustments.
+```
+
+## A/B Testing Prompt
+
+```
+A/B test analysis:
+
+Design A: [minimalist approach]
+Design B: [maximalist approach]
+
+Compare for:
+1. User attention capture (first 3 seconds)
+2. Information hierarchy clarity
+3. Emotional impact and brand perception
+4. Conversion optimization potential
+5. Target audience alignment ([describe audience])
+
+Recommend which to A/B test in production and why.
+```
+
+## Quick Quality Check Template
+
+```
+Rate this asset 1-10 for:
+1. Aesthetic quality
+2. Color harmony
+3. Composition balance
+4. Professional polish
+
+Overall: X/10. Brief justification.
+```
+
+## Comprehensive Evaluation Template
+
+```
+Comprehensive design asset evaluation:
+
+## Aesthetic Alignment
+- Target style: [describe]
+- Actual style: [analyze]
+- Match quality: [1-10]
+
+## Technical Quality
+- Resolution: [assess]
+- Compression: [check artifacts]
+- Aspect ratio: [verify]
+
+## Color Analysis
+- Dominant colors: [list hex codes]
+- Harmony: [evaluate]
+- Mood: [describe]
+
+## Composition
+- Balance: [analyze]
+- Focal points: [identify]
+- Negative space: [evaluate]
+
+## Integration Readiness
+- Text overlay: [rate 1-10]
+- UI compatibility: [assess]
+- Responsive suitability: [evaluate]
+
+Overall Score: X/10
+Key Strengths: [list]
+Improvements Needed: [list]
+```

package/skills/ck-frontend-design/references/analysis-techniques.md

@@ -0,0 +1,118 @@
+# Advanced Analysis Techniques
+
+Advanced strategies for visual analysis and testing.
+
+## Batch Analysis for Rapid Iteration
+
+Analyze multiple generations simultaneously:
+
+```bash
+# Generate 3 variations with fast model
+for i in {1..3}; do
+  python scripts/gemini_batch_process.py \
+    --task generate \
+    --prompt "[prompt with variation-$i twist]" \
+    --output docs/assets/var-$i \
+    --model imagen-4.0-fast-generate-001 \
+    --aspect-ratio 16:9
+done
+
+# Batch analyze all variations
+python scripts/gemini_batch_process.py \
+  --files docs/assets/var-*.png \
+  --task analyze \
+  --prompt "Rank these variations 1-3 with scores. Identify winner." \
+  --output docs/assets/batch-analysis.md \
+  --model gemini-2.5-flash
+```
+
+## Contextual Testing
+
+Test assets in actual UI context:
+
+1. **Mock up UI overlay** (use design tool or code)
+2. **Capture screenshot** of asset with real UI elements
+3. **Analyze integrated version** for readability, hierarchy, contrast
+
+```bash
+# After creating mockup with UI overlay
+python scripts/gemini_batch_process.py \
+  --files docs/assets/hero-mockup-with-ui.png \
+  --task analyze \
+  --prompt "Evaluate this hero section with actual UI:
+1. Headline readability over image
+2. CTA button visibility and contrast
+3. Navigation bar integration
+4. Overall visual hierarchy effectiveness
+Provide WCAG contrast ratio estimates." \
+  --output docs/assets/ui-integration-test.md \
+  --model gemini-2.5-flash
+```
+
+## A/B Testing Analysis
+
+Compare design directions objectively:
+
+```bash
+python scripts/gemini_batch_process.py \
+  --files docs/assets/design-a.png docs/assets/design-b.png \
+  --task analyze \
+  --prompt "A/B test analysis:
+
+Design A: [minimalist approach]
+Design B: [maximalist approach]
+
+Compare for:
+1. User attention capture (first 3 seconds)
+2. Information hierarchy clarity
+3. Emotional impact and brand perception
+4. Conversion optimization potential
+5. Target audience alignment ([describe audience])
+
+Recommend which to A/B test in production and why." \
+  --output docs/assets/ab-test-analysis.md \
+  --model gemini-2.5-flash
+```
+
+## Iteration Strategy
+
+When score < 6/10:
+
+1. **Identify top 3 weaknesses** from analysis
+2. **Address each in refined prompt**
+3. **Regenerate with fast model** first
+4. **Re-analyze before committing** to standard model
+5. **Iterate until score ≥ 7/10**
+
+Example:
+```bash
+# First attempt scores 5/10 - "colors too muted, composition unbalanced"
+
+# Refine prompt addressing specific issues
+python scripts/gemini_batch_process.py \
+  --task generate \
+  --prompt "[original prompt] + vibrant saturated colors, dynamic diagonal composition" \
+  --output docs/assets/hero-v2 \
+  --model imagen-4.0-fast-generate-001
+
+# Re-analyze
+python scripts/gemini_batch_process.py \
+  --files docs/assets/hero-v2.png \
+  --task analyze \
+  --prompt "[same evaluation criteria]" \
+  --output docs/assets/analysis-v2.md
+```
+
+## Documentation Strategy
+
+Save analysis reports for design system documentation:
+
+```
+docs/
+  assets/
+    hero-image.png
+    hero-analysis.md       # Analysis report
+    hero-color-palette.md  # Extracted colors
+  design-guidelines/
+    asset-usage.md         # Guidelines derived from analysis
+```