cokit-cli 1.0.9 → 1.2.2

package/skills/fix/references/skill-activation-matrix.md

@@ -0,0 +1,65 @@
+# Skill Activation Matrix
+
+When to activate each skill during fixing workflows.
+
+## Always Activate
+
+| Skill | Reason |
+|-------|--------|
+| `debug` | Core to all fix workflows - find root cause first |
+
+## Conditional Activation
+
+| Skill | Activate When |
+|-------|---------------|
+| `problem-solving` | Stuck on approach, multiple failed attempts |
+| `sequential-thinking` | Complex logic chain, multi-step reasoning needed |
+| `brainstorming` | Multiple valid approaches, architecture decision |
+| `context-engineering` | Fixing AI/LLM/agent code, context window issues |
+| ImageMagick/FFmpeg | Image/video processing, visual asset manipulation |
+
+## Agent Usage
+
+| Agent | Activate When |
+|----------|---------------|
+| `debugger` | Root cause unclear, need deep investigation |
+| `Explore` (parallel) | Scout multiple areas simultaneously |
+| `Bash` (parallel) | Verify implementation (typecheck, lint, build) |
+| `researcher` | External docs needed, latest best practices |
+| `planner` | Complex fix needs breakdown, multiple phases |
+| `tester` | After implementation, verify fix works |
+| `code-reviewer` | After fix, verify quality and security |
+| `git-manager` | After approval, commit changes |
+| `docs-manager` | API/behavior changes need doc updates |
+| `project-manager` | Major fix impacts roadmap/plan status |
+
+## Parallel Patterns
+
+See `references/parallel-exploration.md` for detailed patterns.
+
+| When | Parallel Strategy |
+|------|-------------------|
+| Root cause unclear | 2-3 `Explore` agents on different areas |
+| Multi-module fix | `Explore` each module in parallel |
+| After implementation | `Bash` agents: typecheck + lint + build |
+| Before commit | `Bash` agents: test + build + lint |
+
+## Workflow → Skills Map
+
+| Workflow | Skills Activated |
+|----------|------------------|
+| Quick | `debug`, `code-reviewer`, parallel `Bash` verification |
+| Standard | Above + `problem-solving`, `sequential-thinking`, `tester`, parallel `Explore` |
+| Deep | All above + `brainstorming`, `context-engineering`, `researcher`, `planner` |
+| Parallel | Per-issue workflow + coordination via parallel agents |
+
+## Detection Triggers
+
+| Keyword/Pattern | Skill to Consider |
+|-----------------|-------------------|
+| "AI", "LLM", "agent", "context" | `context-engineering` |
+| "stuck", "tried everything" | `problem-solving` |
+| "complex", "multi-step" | `sequential-thinking` |
+| "which approach", "options" | `brainstorming` |
+| "latest docs", "best practice" | `researcher` agent |
+| Screenshot attached | Visual analysis |

package/skills/fix/references/workflow-ci.md

@@ -0,0 +1,28 @@
+# CI/CD Fix Workflow
+
+For GitHub Actions failures and CI/CD pipeline issues.
+
+## Prerequisites
+- `gh` CLI installed and authorized
+- GitHub Actions URL or run ID
+
+## Workflow
+
+1. **Fetch logs** with `debugger` agent:
+   ```bash
+   gh run view <run-id> --log-failed
+   gh run view <run-id> --log
+   ```
+
+2. **Analyze** root cause from logs
+
+3. **Implement fix** based on analysis
+
+4. **Test locally** with `tester` agent before pushing
+
+5. **Iterate** if tests fail, repeat from step 3
+
+## Notes
+- If `gh` unavailable, instruct user to install: `gh auth login`
+- Check both failed step and preceding steps for context
+- Common issues: env vars, dependencies, permissions, timeouts

package/skills/fix/references/workflow-deep.md

@@ -0,0 +1,91 @@
+# Deep Workflow
+
+Full pipeline with research, brainstorming, and planning for complex issues.
+
+## Steps
+
+### Step 1: Debug & Parallel Investigation
+Activate `debug` skill. Launch 2-3 `Explore` agents in parallel:
+```
+Task("Explore", "Find error origin", "Trace error")
+Task("Explore", "Find affected components", "Map deps")
+Task("Explore", "Find similar patterns", "Find patterns")
+```
+See `references/parallel-exploration.md` for patterns.
+
+**Output:** `✓ Step 1: Root cause - [summary], system impact: [scope]`
+
+### Step 2: Research
+Use `researcher` agent for external knowledge.
+
+- Search latest docs, best practices
+- Find similar issues/solutions
+- Gather security advisories if relevant
+
+**Output:** `✓ Step 2: Research complete - [key findings]`
+
+### Step 3: Brainstorm
+Activate `brainstorming` skill.
+
+- Evaluate multiple approaches
+- Consider trade-offs
+- Get user input on preferred direction
+
+**Output:** `✓ Step 3: Approach selected - [chosen approach]`
+
+### Step 4: Plan
+Use `planner` agent to create implementation plan.
+
+- Break down into phases
+- Identify dependencies
+- Define success criteria
+
+**Output:** `✓ Step 4: Plan created - [N] phases`
+
+### Step 5: Implement
+Implement per plan. Use `context-engineering`, `sequential-thinking`, `problem-solving`.
+
+**Parallel Verification:** Launch `Bash` agents: typecheck + lint + build
+See `references/parallel-exploration.md`
+
+**Output:** `✓ Step 5: Implemented - [N] files, [M] phases, verified`
+
+### Step 6: Test
+Use `tester` agent.
+
+- Comprehensive testing
+- Edge cases, security, performance
+- If fail → debug, fix, repeat
+
+**Output:** `✓ Step 6: Tests [X/X passed]`
+
+### Step 7: Review
+Use `code-reviewer` agent.
+
+See `references/review-cycle.md` for mode-specific handling.
+
+**Output:** `✓ Step 7: Review [score]/10 - [status]`
+
+### Step 8: Finalize
+- Use `project-manager` agent to update roadmap
+- Use `docs-manager` agent for documentation
+- Use `git-manager` agent for commit
+
+**Output:** `✓ Step 8: Complete - [actions taken]`
+
+## Skills/Agents Activated
+
+| Step | Skills/Agents |
+|------|------------------|
+| 1 | `debug`, parallel `Explore` agents for investigation |
+| 2 | `researcher` |
+| 3 | `brainstorm` |
+| 4 | `planner` |
+| 5 | `problem-solving`, `sequential-thinking`, `context-engineering`, parallel `Bash` |
+| 6 | `tester` |
+| 7 | `code-reviewer` |
+| 8 | `project-manager`, `docs-manager`, `Bash` |
+
+**Rules:** Don't skip steps. Validate before proceeding. One phase at a time.
+**Frontend:** Use `agent-browser` or browser automation tools to verify.
+**Visual Assets:** Use ImageMagick/FFmpeg CLI for image/video processing.

package/skills/fix/references/workflow-logs.md

@@ -0,0 +1,36 @@
+# Log Analysis Fix Workflow
+
+For fixing issues from application logs.
+
+## Prerequisites
+- Log file at `./logs.txt` or similar
+
+## Setup (if logs missing)
+
+Add permanent log piping to project config:
+- **Bash/Unix**: `command 2>&1 | tee logs.txt`
+- **PowerShell**: `command *>&1 | Tee-Object logs.txt`
+
+## Workflow
+
+1. **Read logs** with `Grep` (use `head_limit: 30` initially)
+   - Increase limit if insufficient context
+
+2. **Analyze** with `debugger` agent for root causes
+
+3. **Scout** codebase with `scout` agent for issue locations
+
+4. **Plan** fix with `planner` agent
+
+5. **Implement** the fix
+
+6. **Test** with `tester` agent
+
+7. **Review** with `code-reviewer` agent
+
+8. **Iterate** if issues remain, repeat from step 3
+
+## Tips
+- Focus on last N lines first (most recent errors)
+- Look for stack traces, error codes, timestamps
+- Check for patterns/repeated errors

package/skills/fix/references/workflow-quick.md

@@ -0,0 +1,59 @@
+# Quick Workflow
+
+Fast debug-fix-review cycle for simple issues.
+
+## Steps
+
+### Step 1: Debug
+Activate `debug` skill. Find root cause quickly. Verify the root cause with multiple `Explore` agents in parallel.
+- Read error message/logs
+- Locate affected file(s)
+- Identify exact fix needed
+
+**Output:** `✓ Step 1: Root cause - [brief description]`
+
+### Step 2: Fix & Verify
+Implement the fix directly.
+- Make minimal changes
+- Follow existing patterns
+
+**Parallel Verification:**
+Launch `Bash` agents in parallel:
+```
+Task("Bash", "Run typecheck", "Verify types")
+Task("Bash", "Run lint", "Verify lint")
+```
+
+See `references/parallel-exploration.md` for patterns.
+
+**Output:** `✓ Step 2: Fixed - [N] files, verified (types/lint passed)`
+
+### Step 3: Verify
+Use `code-reviewer` agent for quick review.
+
+Prompt: "Quick review of fix for [issue]. Check: correctness, security, no regressions. Score X/10."
+
+**Review handling:** See `references/review-cycle.md`
+
+**Output:** `✓ Step 3: Review [score]/10 - [status]`
+
+### Step 4: Complete
+Report summary to user.
+
+**If autonomous mode:** Ask to commit via `git-manager` agent if score >= 9.0
+**If HITL mode:** Ask user next action
+
+**Output:** `✓ Step 4: Complete - [action]`
+
+## Skills/Agents Activated
+
+- `debug` - Always (Step 1)
+- Parallel `git-manager` - Verification (Step 2)
+- `code-reviewer` agent - Always (Step 3)
+- `context-engineering` - If dealing with AI/LLM code
+
+## Notes
+
+- Skip if review fails → escalate to Standard workflow
+- Total steps: 4 (vs 5-6 in Standard/Deep)
+- No planning phase needed

package/skills/fix/references/workflow-standard.md

@@ -0,0 +1,86 @@
+# Standard Workflow
+
+Full pipeline for moderate complexity issues.
+
+## Steps
+
+### Step 1: Debug & Investigate
+Activate `debug` skill. Use `debugger` agent if needed.
+
+- Read error messages, logs, stack traces
+- Reproduce the issue
+- Trace backward to root cause
+- Identify all affected files
+
+**Output:** `✓ Step 1: Root cause - [summary], [N] files affected`
+
+### Step 2: Parallel Scout
+Launch multiple `Explore` agents in parallel to scout and verify the root cause.
+
+**Pattern:** In SINGLE message, launch 2-3 Explore agents:
+```
+Task("Explore", "Find [area1] files related to issue", "Scout area1")
+Task("Explore", "Find [area2] patterns/usage", "Scout area2")
+Task("Explore", "Find [area3] tests/dependencies", "Scout area3")
+```
+
+- Only if unclear which files need changes
+- Find patterns, similar implementations, dependencies
+
+See `references/parallel-exploration.md` for patterns.
+
+**Output:** `✓ Step 2: Scouted [N] areas - Found [M] related files`
+
+### Step 3: Implement Fix
+Fix the issue following debugging findings.
+
+- Apply `problem-solving` skill if stuck
+- Use `sequential-thinking` for complex logic
+
+**After implementation - Parallel Verification:**
+Launch `Bash` agents in parallel to verify:
+```
+Task("Bash", "Run typecheck", "Verify types")
+Task("Bash", "Run lint", "Verify lint")
+Task("Bash", "Run build", "Verify build")
+```
+
+**Output:** `✓ Step 3: Implemented - [N] files, verified (types/lint/build passed)`
+
+### Step 4: Test
+Use `tester` agent to run tests.
+
+- Write new tests if needed
+- Run existing test suite
+- If fail → use `debugger`, fix, repeat
+
+**Output:** `✓ Step 4: Tests [X/X passed]`
+
+### Step 5: Review
+Use `code-reviewer` agent.
+
+See `references/review-cycle.md` for mode-specific handling.
+
+**Output:** `✓ Step 5: Review [score]/10 - [status]`
+
+### Step 6: Finalize
+- Report summary to user
+- Ask to commit via `git-manager` agent
+- Update docs if needed via `docs-manager`
+
+**Output:** `✓ Step 6: Complete - [action]`
+
+## Skills/Agents Activated
+
+| Step | Skills/Agents |
+|------|------------------|
+| 1 | `debug`, `debugger` agent |
+| 2 | Multiple `Explore` agents in parallel (optional) |
+| 3 | `problem-solving`, `sequential-thinking`, parallel `Bash` for verification |
+| 4 | `tester` agent |
+| 5 | `code-reviewer` agent |
+| 6 | `git-manager`, `docs-manager` agents |
+
+**Rules:** Don't skip steps. Validate before proceeding. One phase at a time.
+**Frontend:** Use `agent-browser` or browser automation tools to verify.
+**Visual Assets:** Use ImageMagick/FFmpeg CLI for image/video processing.

package/skills/fix/references/workflow-test.md

@@ -0,0 +1,36 @@
+# Test Failure Fix Workflow
+
+For fixing failing tests and test suite issues.
+
+## Workflow
+
+1. **Compile first** with `tester` agent
+   - Fix all syntax errors before running tests
+
+2. **Run tests** and collect failures
+
+3. **Debug** with `debugger` agent for root causes
+
+4. **Plan** fix with `planner` agent
+
+5. **Implement** fixes step by step
+
+6. **Re-test** with `tester` agent
+
+7. **Review** with `code-reviewer` agent
+
+8. **Iterate** if tests still fail, repeat from step 2
+
+## Common Commands
+```bash
+npm test
+bun test
+pytest
+go test ./...
+```
+
+## Tips
+- Run single failing test first for faster iteration
+- Check test assertions vs actual behavior
+- Verify test fixtures/mocks are correct
+- Don't modify tests to pass unless test is wrong

package/skills/fix/references/workflow-types.md

@@ -0,0 +1,33 @@
+# Type Error Fix Workflow
+
+Quick workflow for TypeScript/type errors.
+
+## Commands
+```bash
+bun run typecheck
+tsc --noEmit
+npx tsc --noEmit
+```
+
+## Rules
+- Fix ALL type errors, don't stop at first
+- **NEVER use `any` just to pass** - find proper types
+- Repeat until zero errors
+
+## Common Fixes
+- Missing type imports
+- Incorrect property access
+- Null/undefined handling
+- Generic type parameters
+- Union type narrowing
+
+## Workflow
+1. Run typecheck command
+2. Fix errors one by one
+3. Re-run typecheck
+4. Repeat until clean
+
+## Tips
+- Group related errors (same root cause)
+- Check `@types/*` packages for library types
+- Use `unknown` + type guards instead of `any`

package/skills/fix/references/workflow-ui.md

@@ -0,0 +1,34 @@
+# UI Fix Workflow
+
+For fixing visual/UI issues. Requires design skills.
+
+## Required Skills (activate in order)
+1. `ui-styling` - Design patterns and components (ALWAYS FIRST)
+2. `frontend-design` - Implementation patterns
+
+## Pre-fix Research
+Use `docs-seeker` skill to research:
+- Design patterns for the product type
+- Accessibility best practices
+- Component styling guidelines
+
+## Workflow
+
+1. **Analyze** screenshots/videos visually
+
+2. **Implement** fix with `ui-ux-designer` agent
+
+3. **Verify** with screenshot comparison
+   - Capture parent container, not whole page
+   - Compare to design guidelines
+   - Iterate until correct
+
+4. **DevTools check** with `agent-browser` or browser automation tools
+
+5. **Test** compilation with `tester` agent
+
+6. **Document** updates to `./docs/design-guidelines.md` if needed
+
+## Tips
+- Read `./docs/design-guidelines.md` first
+- Use ImageMagick/FFmpeg CLI for image editing

package/skills/frontend-design/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: frontend-design
+description: Create polished frontend interfaces from designs/screenshots. Use for web components, replicating UI designs, quick prototypes, avoiding AI slop.
+---
+
+Create distinctive, production-grade frontend interfaces. Implement real working code with exceptional aesthetic attention.
+
+## Workflow Selection
+
+Choose workflow based on input type:
+
+| Input | Workflow | Reference |
+|-------|----------|-----------|
+| Screenshot | Replicate exactly | `./references/workflow-screenshot.md` |
+| Quick task | Rapid implementation | `./references/workflow-quick.md` |
+| Describe only | Document for devs | `./references/workflow-describe.md` |
+| From scratch | Design Thinking below | - |
+
+**All workflows**: Activate `ui-styling` skill FIRST for design patterns and component library.
+
+## Screenshot/Video Replication (Quick Reference)
+
+1. **Analyze** visually - extract colors, fonts, spacing, effects
+2. **Plan** with `ui-ux-designer` agent - create phased implementation
+3. **Implement** - match source precisely
+4. **Verify** - compare to original
+5. **Document** - update `./docs/design-guidelines.md` if approved
+
+See specific workflow files for detailed steps.
+
+## Design Thinking (From Scratch)
+
+Before coding, 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**: Execute with precision. Bold maximalism and refined minimalism both work - intentionality is key.
+
+## Aesthetics Guidelines
+
+- **Typography**: Avoid Arial/Inter; use distinctive, characterful fonts. Pair display + body fonts.
+- **Color**: Commit to cohesive palette. CSS variables. Dominant colors with sharp accents.
+- **Motion**: CSS-first, anime.js for complex (`./references/animejs.md`). Orchestrated page loads > scattered micro-interactions.
+- **Spatial**: Unexpected layouts. Asymmetry. Overlap. Negative space OR controlled density.
+- **Backgrounds**: Atmosphere over solid colors. Gradients, noise, patterns, shadows, grain.
+- **Assets**: Process with ImageMagick, FFmpeg, RMBG CLI tools
+
+## Asset & Analysis References
+
+| Task | Reference |
+|------|-----------|
+| Generate assets | `./references/asset-generation.md` |
+| Analyze quality | `./references/visual-analysis-overview.md` |
+| Extract guidelines | `./references/design-extraction-overview.md` |
+| Optimization | `./references/technical-overview.md` |
+| Animations | `./references/animejs.md` |
+
+Quick start: `./references/asset-generation.md`
+
+## Anti-Patterns (AI Slop)
+
+NEVER use:
+- Overused fonts: Inter, Roboto, Arial, Space Grotesk
+- Cliched colors: purple gradients on white
+- Predictable layouts, cookie-cutter patterns
+
+DO:
+- Vary themes (light/dark), fonts, aesthetics per project
+- Match complexity to vision (maximalist = elaborate; minimalist = precise)
+- Make unexpected, context-specific choices
+
+Remember: The AI agent is capable of extraordinary creative work. Commit fully to distinctive visions.

package/skills/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