cokit-cli 1.3.0 → 1.4.0

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

@@ -0,0 +1,400 @@
+---
+name: ck-frontend-development
+description: Build React/TypeScript frontends with modern patterns. Use for components, Suspense, lazy loading, useSuspenseQuery, MUI v7 styling, TanStack Router, performance optimization.
+argument-hint: "[component or feature]"
+---
+
+# Frontend Development Guidelines
+
+## Purpose
+
+Comprehensive guide for modern React development, emphasizing Suspense-based data fetching, lazy loading, proper file organization, and performance optimization.
+
+## When to Use This Skill
+
+- Creating new components or pages
+- Building new features
+- Fetching data with TanStack Query
+- Setting up routing with TanStack Router
+- Styling components with MUI v7
+- Performance optimization
+- Organizing frontend code
+- TypeScript best practices
+
+---
+
+## Quick Start
+
+### New Component Checklist
+
+Creating a component? Follow this checklist:
+
+- [ ] Use `React.FC<Props>` pattern with TypeScript
+- [ ] Lazy load if heavy component: `React.lazy(() => import())`
+- [ ] Wrap in `<SuspenseLoader>` for loading states
+- [ ] Use `useSuspenseQuery` for data fetching
+- [ ] Import aliases: `@/`, `~types`, `~components`, `~features`
+- [ ] Styles: Inline if <100 lines, separate file if >100 lines
+- [ ] Use `useCallback` for event handlers passed to children
+- [ ] Default export at bottom
+- [ ] No early returns with loading spinners
+- [ ] Use `useMuiSnackbar` for user notifications
+
+### New Feature Checklist
+
+Creating a feature? Set up this structure:
+
+- [ ] Create `features/{feature-name}/` directory
+- [ ] Create subdirectories: `api/`, `components/`, `hooks/`, `helpers/`, `types/`
+- [ ] Create API service file: `api/{feature}Api.ts`
+- [ ] Set up TypeScript types in `types/`
+- [ ] Create route in `routes/{feature-name}/index.tsx`
+- [ ] Lazy load feature components
+- [ ] Use Suspense boundaries
+- [ ] Export public API from feature `index.ts`
+
+---
+
+## Import Aliases Quick Reference
+
+| Alias | Resolves To | Example |
+|-------|-------------|---------|
+| `@/` | `src/` | `import { apiClient } from '@/lib/apiClient'` |
+| `~types` | `src/types` | `import type { User } from '~types/user'` |
+| `~components` | `src/components` | `import { SuspenseLoader } from '~components/SuspenseLoader'` |
+| `~features` | `src/features` | `import { authApi } from '~features/auth'` |
+
+Defined in: [vite.config.ts](../../vite.config.ts) lines 180-185
+
+---
+
+## Common Imports Cheatsheet
+
+```typescript
+// React & Lazy Loading
+import React, { useState, useCallback, useMemo } from 'react';
+const Heavy = React.lazy(() => import('./Heavy'));
+
+// MUI Components
+import { Box, Paper, Typography, Button, Grid } from '@mui/material';
+import type { SxProps, Theme } from '@mui/material';
+
+// TanStack Query (Suspense)
+import { useSuspenseQuery, useQueryClient } from '@tanstack/react-query';
+
+// TanStack Router
+import { createFileRoute } from '@tanstack/react-router';
+
+// Project Components
+import { SuspenseLoader } from '~components/SuspenseLoader';
+
+// Hooks
+import { useAuth } from '@/hooks/useAuth';
+import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';
+
+// Types
+import type { Post } from '~types/post';
+```
+
+---
+
+## Topic Guides
+
+### 🎨 Component Patterns
+
+**Modern React components use:**
+- `React.FC<Props>` for type safety
+- `React.lazy()` for code splitting
+- `SuspenseLoader` for loading states
+- Named const + default export pattern
+
+**Key Concepts:**
+- Lazy load heavy components (DataGrid, charts, editors)
+- Always wrap lazy components in Suspense
+- Use SuspenseLoader component (with fade animation)
+- Component structure: Props → Hooks → Handlers → Render → Export
+
+**[📖 Complete Guide: resources/component-patterns.md](resources/component-patterns.md)**
+
+---
+
+### 📊 Data Fetching
+
+**PRIMARY PATTERN: useSuspenseQuery**
+- Use with Suspense boundaries
+- Cache-first strategy (check grid cache before API)
+- Replaces `isLoading` checks
+- Type-safe with generics
+
+**API Service Layer:**
+- Create `features/{feature}/api/{feature}Api.ts`
+- Use `apiClient` axios instance
+- Centralized methods per feature
+- Route format: `/form/route` (NOT `/api/form/route`)
+
+**[📖 Complete Guide: resources/data-fetching.md](resources/data-fetching.md)**
+
+---
+
+### 📁 File Organization
+
+**features/ vs components/:**
+- `features/`: Domain-specific (posts, comments, auth)
+- `components/`: Truly reusable (SuspenseLoader, CustomAppBar)
+
+**Feature Subdirectories:**
+```
+features/
+  my-feature/
+    api/          # API service layer
+    components/   # Feature components
+    hooks/        # Custom hooks
+    helpers/      # Utility functions
+    types/        # TypeScript types
+```
+
+**[📖 Complete Guide: resources/file-organization.md](resources/file-organization.md)**
+
+---
+
+### 🎨 Styling
+
+**Inline vs Separate:**
+- <100 lines: Inline `const styles: Record<string, SxProps<Theme>>`
+- >100 lines: Separate `.styles.ts` file
+
+**Primary Method:**
+- Use `sx` prop for MUI components
+- Type-safe with `SxProps<Theme>`
+- Theme access: `(theme) => theme.palette.primary.main`
+
+**MUI v7 Grid:**
+```typescript
+<Grid size={{ xs: 12, md: 6 }}>  // ✅ v7 syntax
+<Grid xs={12} md={6}>             // ❌ Old syntax
+```
+
+**[📖 Complete Guide: resources/styling-guide.md](resources/styling-guide.md)**
+
+---
+
+### 🛣️ Routing
+
+**TanStack Router - Folder-Based:**
+- Directory: `routes/my-route/index.tsx`
+- Lazy load components
+- Use `createFileRoute`
+- Breadcrumb data in loader
+
+**Example:**
+```typescript
+import { createFileRoute } from '@tanstack/react-router';
+import { lazy } from 'react';
+
+const MyPage = lazy(() => import('@/features/my-feature/components/MyPage'));
+
+export const Route = createFileRoute('/my-route/')({
+    component: MyPage,
+    loader: () => ({ crumb: 'My Route' }),
+});
+```
+
+**[📖 Complete Guide: resources/routing-guide.md](resources/routing-guide.md)**
+
+---
+
+### ⏳ Loading & Error States
+
+**CRITICAL RULE: No Early Returns**
+
+```typescript
+// ❌ NEVER - Causes layout shift
+if (isLoading) {
+    return <LoadingSpinner />;
+}
+
+// ✅ ALWAYS - Consistent layout
+<SuspenseLoader>
+    <Content />
+</SuspenseLoader>
+```
+
+**Why:** Prevents Cumulative Layout Shift (CLS), better UX
+
+**Error Handling:**
+- Use `useMuiSnackbar` for user feedback
+- NEVER `react-toastify`
+- TanStack Query `onError` callbacks
+
+**[📖 Complete Guide: resources/loading-and-error-states.md](resources/loading-and-error-states.md)**
+
+---
+
+### ⚡ Performance
+
+**Optimization Patterns:**
+- `useMemo`: Expensive computations (filter, sort, map)
+- `useCallback`: Event handlers passed to children
+- `React.memo`: Expensive components
+- Debounced search (300-500ms)
+- Memory leak prevention (cleanup in useEffect)
+
+**[📖 Complete Guide: resources/performance.md](resources/performance.md)**
+
+---
+
+### 📘 TypeScript
+
+**Standards:**
+- Strict mode, no `any` type
+- Explicit return types on functions
+- Type imports: `import type { User } from '~types/user'`
+- Component prop interfaces with JSDoc
+
+**[📖 Complete Guide: resources/typescript-standards.md](resources/typescript-standards.md)**
+
+---
+
+### 🔧 Common Patterns
+
+**Covered Topics:**
+- React Hook Form with Zod validation
+- DataGrid wrapper contracts
+- Dialog component standards
+- `useAuth` hook for current user
+- Mutation patterns with cache invalidation
+
+**[📖 Complete Guide: resources/common-patterns.md](resources/common-patterns.md)**
+
+---
+
+### 📚 Complete Examples
+
+**Full working examples:**
+- Modern component with all patterns
+- Complete feature structure
+- API service layer
+- Route with lazy loading
+- Suspense + useSuspenseQuery
+- Form with validation
+
+**[📖 Complete Guide: resources/complete-examples.md](resources/complete-examples.md)**
+
+---
+
+## Navigation Guide
+
+| Need to... | Read this resource |
+|------------|-------------------|
+| Create a component | [component-patterns.md](resources/component-patterns.md) |
+| Fetch data | [data-fetching.md](resources/data-fetching.md) |
+| Organize files/folders | [file-organization.md](resources/file-organization.md) |
+| Style components | [styling-guide.md](resources/styling-guide.md) |
+| Set up routing | [routing-guide.md](resources/routing-guide.md) |
+| Handle loading/errors | [loading-and-error-states.md](resources/loading-and-error-states.md) |
+| Optimize performance | [performance.md](resources/performance.md) |
+| TypeScript types | [typescript-standards.md](resources/typescript-standards.md) |
+| Forms/Auth/DataGrid | [common-patterns.md](resources/common-patterns.md) |
+| See full examples | [complete-examples.md](resources/complete-examples.md) |
+
+---
+
+## Core Principles
+
+1. **Lazy Load Everything Heavy**: Routes, DataGrid, charts, editors
+2. **Suspense for Loading**: Use SuspenseLoader, not early returns
+3. **useSuspenseQuery**: Primary data fetching pattern for new code
+4. **Features are Organized**: api/, components/, hooks/, helpers/ subdirs
+5. **Styles Based on Size**: <100 inline, >100 separate
+6. **Import Aliases**: Use @/, ~types, ~components, ~features
+7. **No Early Returns**: Prevents layout shift
+8. **useMuiSnackbar**: For all user notifications
+
+---
+
+## Quick Reference: File Structure
+
+```
+src/
+  features/
+    my-feature/
+      api/
+        myFeatureApi.ts       # API service
+      components/
+        MyFeature.tsx         # Main component
+        SubComponent.tsx      # Related components
+      hooks/
+        useMyFeature.ts       # Custom hooks
+        useSuspenseMyFeature.ts  # Suspense hooks
+      helpers/
+        myFeatureHelpers.ts   # Utilities
+      types/
+        index.ts              # TypeScript types
+      index.ts                # Public exports
+
+  components/
+    SuspenseLoader/
+      SuspenseLoader.tsx      # Reusable loader
+    CustomAppBar/
+      CustomAppBar.tsx        # Reusable app bar
+
+  routes/
+    my-route/
+      index.tsx               # Route component
+      create/
+        index.tsx             # Nested route
+```
+
+---
+
+## Modern Component Template (Quick Copy)
+
+```typescript
+import React, { useState, useCallback } from 'react';
+import { Box, Paper } from '@mui/material';
+import { useSuspenseQuery } from '@tanstack/react-query';
+import { featureApi } from '../api/featureApi';
+import type { FeatureData } from '~types/feature';
+
+interface MyComponentProps {
+    id: number;
+    onAction?: () => void;
+}
+
+export const MyComponent: React.FC<MyComponentProps> = ({ id, onAction }) => {
+    const [state, setState] = useState<string>('');
+
+    const { data } = useSuspenseQuery({
+        queryKey: ['feature', id],
+        queryFn: () => featureApi.getFeature(id),
+    });
+
+    const handleAction = useCallback(() => {
+        setState('updated');
+        onAction?.();
+    }, [onAction]);
+
+    return (
+        <Box sx={{ p: 2 }}>
+            <Paper sx={{ p: 3 }}>
+                {/* Content */}
+            </Paper>
+        </Box>
+    );
+};
+
+export default MyComponent;
+```
+
+For complete examples, see [resources/complete-examples.md](resources/complete-examples.md)
+
+---
+
+## Related Skills
+
+- **error-tracking**: Error tracking with Sentry (applies to frontend too)
+- **backend-dev-guidelines**: Backend API patterns that frontend consumes
+
+---
+
+**Skill Status**: Modular structure with progressive loading for optimal context management

package/skills/ck-git/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: ck-git
+description: "Git operations with conventional commits. Use for staging, committing, pushing, PRs, merges. Auto-splits commits by type/scope. Security scans for secrets."
+argument-hint: "cm|cp|pr|merge [args]"
+---
+
+# Git Operations
+
+## Default (No Arguments)
+
+If invoked without arguments, ask the user to present available git operations:
+
+| Operation | Description |
+|-----------|-------------|
+| `cm` | Stage files & create commits |
+| `cp` | Stage files, create commits and push |
+| `pr` | Create Pull Request |
+| `merge` | Merge branches |
+
+Present as options by asking the user with header "Git Operation", question "What would you like to do?".
+
+Execute git workflows via `ck-git-manager` subagent to isolate verbose output.
+Activate `ck-context-engineering` skill.
+
+**IMPORTANT:**
+- Sacrifice grammar for the sake of concision.
+- Ensure token efficiency while maintaining high quality.
+- Pass these rules to subagents.
+
+## Arguments
+- `cm`: Stage files & create commits
+- `cp`: Stage files, create commits and push
+- `pr`: Create Pull Request [to-branch] [from-branch]
+  - `to-branch`: Target branch (default: main)
+  - `from-branch`: Source branch (default: current branch)
+- `merge`: Merge [to-branch] [from-branch]
+  - `to-branch`: Target branch (default: main)
+  - `from-branch`: Source branch (default: current branch)
+
+## Quick Reference
+
+| Task | Reference |
+|------|-----------|
+| Commit | `references/workflow-commit.md` |
+| Push | `references/workflow-push.md` |
+| Pull Request | `references/workflow-pr.md` |
+| Merge | `references/workflow-merge.md` |
+| Standards | `references/commit-standards.md` |
+| Safety | `references/safety-protocols.md` |
+| Branches | `references/branch-management.md` |
+| GitHub CLI | `references/gh-cli-guide.md` |
+
+## Core Workflow
+
+### Step 1: Stage + Analyze
+```bash
+git add -A && git diff --cached --stat && git diff --cached --name-only
+```
+
+### Step 2: Security Check
+Scan for secrets before commit:
+```bash
+git diff --cached | grep -iE "(api[_-]?key|token|password|secret|credential)"
+```
+**If secrets found:** STOP, warn user, suggest `.gitignore`.
+
+### Step 3: Split Decision
+
+**NOTE:**
+- Search for related issues on GitHub and add to body.
+- Only use `feat`, `fix`, or `perf` prefixes for files in skills directory (do not use `docs`).
+
+**Split commits if:**
+- Different types mixed (feat + fix, code + docs)
+- Multiple scopes (auth + payments)
+- Config/deps + code mixed
+- FILES > 10 unrelated
+
+**Single commit if:**
+- Same type/scope, FILES ≤ 3, LINES ≤ 50
+
+### Step 4: Commit
+```bash
+git commit -m "type(scope): description"
+```
+
+## Output Format
+```
+✓ staged: N files (+X/-Y lines)
+✓ security: passed
+✓ commit: HASH type(scope): description
+✓ pushed: yes/no
+```
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| Secrets detected | Block commit, show files |
+| No changes | Exit cleanly |
+| Push rejected | Suggest `git pull --rebase` |
+| Merge conflicts | Suggest manual resolution |
+
+## References
+
+- `references/workflow-commit.md` - Commit workflow with split logic
+- `references/workflow-push.md` - Push workflow with error handling
+- `references/workflow-pr.md` - PR creation with remote diff analysis
+- `references/workflow-merge.md` - Branch merge workflow
+- `references/commit-standards.md` - Conventional commit format rules
+- `references/safety-protocols.md` - Secret detection, branch protection
+- `references/branch-management.md` - Naming, lifecycle, strategies
+- `references/gh-cli-guide.md` - GitHub CLI commands reference

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

@@ -0,0 +1,58 @@
+# Commit Workflow
+
+Execute via `ck-git-manager` subagent.
+
+## Tool 1: Stage + Analyze
+```bash
+git add -A && \
+echo "=== STAGED ===" && git diff --cached --stat && \
+echo "=== SECURITY ===" && \
+git diff --cached | grep -c -iE "(api[_-]?key|token|password|secret|credential)" | awk '{print "SECRETS:"$1}' && \
+echo "=== GROUPS ===" && \
+git diff --cached --name-only | awk -F'/' '{
+  if ($0 ~ /\.(md|txt)$/) print "docs:"$0
+  else if ($0 ~ /test|spec/) print "test:"$0
+  else if ($0 ~ /skills|agents/) print "config:"$0
+  else if ($0 ~ /package\.json|lock/) print "deps:"$0
+  else print "code:"$0
+}'
+```
+
+**If SECRETS > 0:** STOP, show matches, block commit.
+
+## Tool 2: Split Decision
+
+NOTE: 
+- Search for related issues on GitHub and add to body.
+- Only use `feat`, `fix`, or `perf` prefixes for files in skills directory (do not use `docs`).
+
+**From groups, decide:**
+
+**A) Single commit:** Same type/scope, FILES ≤ 3, LINES ≤ 50
+
+**B) Multi commit:** Mixed types/scopes, group by:
+- Group 1: `config:` → `chore(config): ...`
+- Group 2: `deps:` → `chore(deps): ...`
+- Group 3: `test:` → `test: ...`
+- Group 4: `code:` → `feat|fix: ...`
+- Group 5: `docs:` → `docs: ...`
+
+## Tool 3: Commit
+
+**Single:**
+```bash
+git commit -m "type(scope): description"
+```
+
+**Multi (sequential):**
+```bash
+git reset && git add file1 file2 && git commit -m "type(scope): desc"
+```
+Repeat for each group.
+
+## Tool 4: Push (if requested)
+```bash
+git push && echo "✓ pushed: yes" || echo "✓ pushed: no"
+```
+
+**Only push if user explicitly requested** ("push", "commit and push").

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

@@ -0,0 +1,48 @@
+# Merge Workflow
+
+Execute via `ck-git-manager` subagent.
+
+## Variables
+- TO_BRANCH: target (defaults to `main`)
+- FROM_BRANCH: source (defaults to current branch)
+
+## Step 1: Sync with Remote
+
+**IMPORTANT: Always merge `main` (or any default branch) to current branch first.**
+
+```bash
+git fetch origin
+git checkout {TO_BRANCH}
+git pull origin {TO_BRANCH}
+```
+
+## Step 2: Merge from REMOTE
+```bash
+git merge origin/{FROM_BRANCH} --no-ff -m "merge: {FROM_BRANCH} into {TO_BRANCH}"
+```
+
+**Why `origin/{FROM_BRANCH}`:** Ensures merging only committed+pushed changes, not local WIP.
+
+## Step 3: Resolve Conflicts
+If conflicts:
+1. Resolve manually
+2. `git add . && git commit`
+3. If clarifications needed, report to main agent
+
+## Step 4: Push
+```bash
+git push origin {TO_BRANCH}
+```
+
+## Pre-Merge Checklist
+- Fetch latest: `git fetch origin`
+- Ensure FROM_BRANCH pushed to remote
+- Check for conflicts: `git merge --no-commit --no-ff origin/{FROM_BRANCH}` then abort
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| Merge conflicts | Resolve manually, then commit |
+| Branch not found | Verify branch name, ensure pushed |
+| Push rejected | `git pull --rebase`, retry |

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

@@ -0,0 +1,58 @@
+# Pull Request Workflow
+
+Execute via `ck-git-manager` subagent.
+
+## Variables
+- TO_BRANCH: target (defaults to `main`)
+- FROM_BRANCH: source (defaults to current branch)
+
+## CRITICAL: Use REMOTE diff
+PRs based on remote branches. Local diff includes unpushed changes.
+
+## Tool 1: Sync + Analyze
+
+**IMPORTANT: Always merge `main` (or any default branch) to current branch first.**
+
+```bash
+git fetch origin && \
+git push -u origin HEAD 2>/dev/null || true && \
+BASE=${BASE_BRANCH:-main} && \
+HEAD=$(git rev-parse --abbrev-ref HEAD) && \
+echo "=== PR: $HEAD → $BASE ===" && \
+echo "=== COMMITS ===" && \
+git log origin/$BASE...origin/$HEAD --oneline && \
+echo "=== FILES ===" && \
+git diff origin/$BASE...origin/$HEAD --stat
+```
+
+**If "Branch not on remote":** Push first, retry.
+
+## Tool 2: Generate Content
+**Title:** Conventional commit format, <72 chars, NO version numbers
+**Body:** Summary bullets + Test plan checklist
+
+## Tool 3: Create PR
+```bash
+gh pr create --base $BASE --head $HEAD --title "..." --body "$(cat <<'EOF'
+## Summary
+- Bullet points
+
+## Test plan
+- [ ] Test item
+EOF
+)"
+```
+
+## DO NOT use (local comparison)
+- ❌ `git diff main...HEAD`
+- ❌ `git diff --cached`
+- ❌ `git status`
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| Branch not on remote | `git push -u origin HEAD`, retry |
+| Empty diff | Warn: "No changes for PR" |
+| Push rejected | `git pull --rebase`, resolve, push |
+| No upstream | `git push -u origin HEAD` |