claude-code-kit 0.7.0__py3-none-any.whl

claude_kit/_payload/skills/performance-optimization/SKILL.md

@@ -0,0 +1,277 @@
+---
+name: performance-optimization
+description: Analyze and optimize application performance covering web vitals, bundle size, code splitting, chunking strategy, and rendering best practices for web frontends.
+argument-hint: [page, component, or "bundle"]
+disable-model-invocation: true
+---
+
+Optimize performance for: $ARGUMENTS.
+
+## Steps
+
+1. **Identify the optimization target**: Determine if this is a bundle optimization, render performance issue, or Core Web Vitals improvement for `$ARGUMENTS`.
+
+2. **Gather baseline metrics**: Run the appropriate analysis tools.
+
+   ### Bundle Analysis
+   ```bash
+   # Use the project's bundle analyzer (examples: vite-bundle-visualizer, webpack-bundle-analyzer, esbuild analyzer)
+   # Run the project's build and check output for chunk sizes
+   ```
+
+   ### Runtime Performance
+   - Use the `auditor` agent or Chrome DevTools to run a Lighthouse trace on the target page
+   - Check for framework-specific warnings in the browser console
+
+3. **Apply optimizations based on category**:
+
+---
+
+### A. Bundle Optimization
+
+#### Code Splitting (Route-Level)
+Every major route should be lazy-loaded where the framework supports it:
+
+**React/Preact example:**
+```typescript
+// App entry point
+const DashboardPage = React.lazy(() => import('./pages/DashboardPage'));
+const DataPage = React.lazy(() => import('./pages/DataPage'));
+
+// Wrap in Suspense
+<Suspense fallback={<Spinner />}>
+  <Route path="/" element={<DashboardPage />} />
+</Suspense>
+```
+
+**Vue example:**
+```javascript
+const routes = [
+  { path: '/', component: () => import('./pages/DashboardPage.vue') },
+  { path: '/data', component: () => import('./pages/DataPage.vue') },
+];
+```
+
+**Angular example:**
+```typescript
+// In routing module
+const routes: Routes = [
+  { path: 'dashboard', loadChildren: () => import('./dashboard/dashboard.module').then(m => m.DashboardModule) },
+];
+```
+
+#### Tree Shaking
+- Import only what you use:
+  ```typescript
+  // GOOD
+  import { IconName, SpecificIcon } from 'icon-library';
+
+  // BAD
+  import * as Icons from 'icon-library';
+  ```
+- Verify chart/visualization library imports are specific (e.g., import only the chart types you need)
+
+#### Chunk Strategy
+| Chunk | Contents | Target Size |
+|-------|----------|-------------|
+| `vendor-core` | Core framework (react/vue/angular) + router | ~40-50KB gz |
+| `vendor-ui` | UI component library | ~30KB gz |
+| `vendor-charts` | Chart/visualization libraries | ~50KB gz (lazy) |
+| `app` | Application code | <100KB gz |
+| Route chunks | Per-page code | <30KB gz each |
+
+**Example configuration (adapt to your bundler):**
+
+Vite:
+```typescript
+build: {
+  rollupOptions: {
+    output: {
+      manualChunks: {
+        'vendor-core': ['framework', 'framework-router'],
+        'vendor-ui': ['ui-library-pkg'],
+        'vendor-charts': ['chart-library'],
+      },
+    },
+  },
+},
+```
+
+Webpack:
+```javascript
+optimization: {
+  splitChunks: {
+    cacheGroups: {
+      vendor: { test: /[\\/]node_modules[\\/]/, name: 'vendor' },
+      // ... custom groups
+    },
+  },
+},
+```
+
+#### Bundle Size Targets
+| Metric | Target | Alert |
+|--------|--------|-------|
+| Initial JS (gzipped) | < 200KB | > 250KB |
+| Largest chunk (gzipped) | < 100KB | > 120KB |
+| Total CSS (gzipped) | < 30KB | > 50KB |
+
+---
+
+### B. UI Rendering Performance
+
+#### Avoid Unnecessary Re-renders
+**React/Preact:**
+```typescript
+// Use memoization for pure display components
+const MetricCard = React.memo(function MetricCard({ title, value }: Props) {
+  return <div>...</div>;
+});
+
+// Use memoization for expensive derivations
+const sortedItems = useMemo(() =>
+  items.sort((a, b) => b.priority - a.priority),
+  [items]
+);
+
+// Use callbacks for handlers passed as props
+const handleFilter = useCallback((value: string) => {
+  setFilter(value);
+}, []);
+```
+
+**Vue:**
+```vue
+<script setup>
+// Use computed properties for derived state
+const sortedItems = computed(() =>
+  items.value.sort((a, b) => b.priority - a.priority)
+);
+</script>
+```
+
+**Angular:**
+```typescript
+// Use OnPush change detection for pure components
+@Component({
+  changeDetection: ChangeDetectionStrategy.OnPush
+})
+```
+
+#### Client State Store Anti-patterns
+**Zustand (React) example:**
+```typescript
+// BAD - subscribes to entire store, re-renders on ANY change
+const store = useStore();
+
+// GOOD - subscribe to specific values
+const items = useStore((s) => s.items);
+const setFilter = useStore((s) => s.setFilter);
+
+// BAD - creates new reference every render
+const filtered = useStore((s) => s.items.filter(i => i.active));
+
+// GOOD - store derived data as state, recompute in actions
+const filteredItems = useStore((s) => s.filteredItems);
+```
+
+**Pinia (Vue) / Vuex:**
+```javascript
+// Use getters for derived state, not computed in components
+const store = useMyStore();
+const filteredItems = store.filteredItems; // getter defined in store
+```
+
+**NgRx (Angular):**
+```typescript
+// Use selectors for derived state
+const filteredItems$ = store.select(selectFilteredItems);
+```
+
+#### Virtualization
+Use virtualization for lists with > 50 items. Examples by framework:
+
+**React:**
+```typescript
+import { useVirtualizer } from '@tanstack/react-virtual';
+
+function VirtualList({ items }: { items: Item[] }) {
+  const parentRef = useRef<HTMLDivElement>(null);
+  const virtualizer = useVirtualizer({
+    count: items.length,
+    getScrollElement: () => parentRef.current,
+    estimateSize: () => 64,
+  });
+
+  return (
+    <div ref={parentRef} className="h-[600px] overflow-auto">
+      <div style={{ height: virtualizer.getTotalSize() }} className="relative w-full">
+        {virtualizer.getVirtualItems().map((virtualItem) => (
+          <div
+            key={virtualItem.key}
+            className="absolute top-0 left-0 w-full"
+            style={{ height: virtualItem.size, transform: `translateY(${virtualItem.start}px)` }}
+          >
+            <ItemRow item={items[virtualItem.index]} />
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+**Vue:** Use `vue-virtual-scroller` or `@tanstack/vue-virtual`
+
+**Angular:** Use `@angular/cdk/scrolling` with `cdk-virtual-scroll-viewport`
+
+---
+
+### C. Core Web Vitals
+
+| Metric | Target | Common Fixes |
+|--------|--------|-------------|
+| LCP < 2.5s | Optimize critical rendering path | Lazy-load below-fold content, preload fonts |
+| FID < 100ms | Minimize main thread work | Code-split heavy components, defer non-critical JS |
+| CLS < 0.1 | Prevent layout shifts | Set explicit dimensions on images/containers, use min-height |
+| INP < 200ms | Fast interactions | Debounce handlers, use framework-specific non-blocking APIs (e.g., React `startTransition`) |
+
+#### Font Loading
+```html
+<!-- Preconnect to font CDN (if using web fonts) -->
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+
+<!-- Or use font-display: swap in CSS -->
+@font-face {
+  font-family: 'CustomFont';
+  font-display: swap;
+  src: url('/fonts/custom.woff2') format('woff2');
+}
+```
+
+#### Image Optimization
+- Use the project's optimized image component if available
+- Specify `width` and `height` attributes to prevent CLS
+- Use `loading="lazy"` for below-fold images
+- Consider using modern formats (WebP, AVIF) with fallbacks
+
+---
+
+4. **Verify improvements**: Re-run analysis tools and compare against baseline.
+
+5. **Report**: Output a before/after comparison table:
+
+   | Metric | Before | After | Change |
+   |--------|--------|-------|--------|
+   | Initial bundle | Xkb | Ykb | -Z% |
+   | LCP | Xs | Ys | -Zms |
+   | ... | ... | ... | ... |
+
+6. **Run build**: Execute the project's build command to confirm the build still passes.
+
+## References
+
+- Check the project's bundler config (e.g., `vite.config.ts`, `webpack.config.js`, `angular.json`)
+- Consult the project's design system documentation for image/icon sizing guidelines
+- Use the project's virtualization library (e.g., `@tanstack/react-virtual`, `vue-virtual-scroller`, `@angular/cdk/scrolling`)

claude_kit/_payload/skills/planning-and-task-breakdown/SKILL.md

@@ -0,0 +1,223 @@
+---
+name: planning-and-task-breakdown
+description: Breaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. Works across all stacks and languages.
+---
+
+# Planning and Task Breakdown
+
+## Overview
+
+Decompose work into small, verifiable tasks with explicit acceptance criteria. Good task breakdown is the difference between an agent that completes work reliably and one that produces a tangled mess. Every task should be small enough to implement, test, and verify in a single focused session.
+
+## When to Use
+
+- You have a spec and need to break it into implementable units
+- A task feels too large or vague to start
+- Work needs to be parallelized across multiple agents or sessions
+- You need to communicate scope to a human
+- The implementation order isn't obvious
+
+**When NOT to use:** Single-file changes with obvious scope, or when the spec already contains well-defined tasks.
+
+## The Planning Process
+
+### Step 1: Enter Plan Mode
+
+Before writing any code, operate in read-only mode:
+
+- Read the spec and relevant codebase sections
+- Identify existing patterns and conventions
+- Map dependencies between components
+- Note risks and unknowns
+
+**Do NOT write code during planning.** The output is a plan document, not implementation.
+
+### Step 2: Identify the Dependency Graph
+
+Map what depends on what:
+
+```
+Database schema
+    │
+    ├── API models/types
+    │       │
+    │       ├── API endpoints
+    │       │       │
+    │       │       └── Frontend API client
+    │       │               │
+    │       │               └── UI components
+    │       │
+    │       └── Validation logic
+    │
+    └── Seed data / migrations
+```
+
+Implementation order follows the dependency graph bottom-up: build foundations first.
+
+### Step 3: Slice Vertically
+
+Instead of building all the database, then all the API, then all the UI — build one complete feature path at a time:
+
+**Bad (horizontal slicing):**
+```
+Task 1: Build entire database schema
+Task 2: Build all API endpoints
+Task 3: Build all UI components
+Task 4: Connect everything
+```
+
+**Good (vertical slicing):**
+```
+Task 1: User can create an account (schema + API + UI for registration)
+Task 2: User can log in (auth schema + API + UI for login)
+Task 3: User can create a task (task schema + API + UI for creation)
+Task 4: User can view task list (query + API + UI for list view)
+```
+
+Each vertical slice delivers working, testable functionality.
+
+### Step 4: Write Tasks
+
+Each task follows this structure:
+
+```markdown
+## Task [N]: [Short descriptive title]
+
+**Description:** One paragraph explaining what this task accomplishes.
+
+**Acceptance criteria:**
+- [ ] [Specific, testable condition]
+- [ ] [Specific, testable condition]
+
+**Verification:**
+- [ ] Tests pass: run the project's test suite for this feature
+- [ ] Build succeeds: run the project's build
+- [ ] Manual check: [description of what to verify]
+
+**Dependencies:** [Task numbers this depends on, or "None"]
+
+**Files likely touched:**
+- `path/to/file`
+- `path/to/test`
+
+**Estimated scope:** [Small: 1-2 files | Medium: 3-5 files | Large: 5+ files]
+```
+
+### Step 5: Order and Checkpoint
+
+Arrange tasks so that:
+
+1. Dependencies are satisfied (build foundation first)
+2. Each task leaves the system in a working state
+3. Verification checkpoints occur after every 2-3 tasks
+4. High-risk tasks are early (fail fast)
+
+Add explicit checkpoints:
+
+```markdown
+## Checkpoint: After Tasks 1-3
+- [ ] All tests pass
+- [ ] Application builds without errors
+- [ ] Core user flow works end-to-end
+- [ ] Review with human before proceeding
+```
+
+## Task Sizing Guidelines
+
+| Size | Files | Scope | Example |
+|------|-------|-------|---------|
+| **XS** | 1 | Single function or config change | Add a validation rule |
+| **S** | 1-2 | One component or endpoint | Add a new API endpoint |
+| **M** | 3-5 | One feature slice | User registration flow |
+| **L** | 5-8 | Multi-component feature | Search with filtering and pagination |
+| **XL** | 8+ | **Too large — break it down further** | — |
+
+If a task is L or larger, it should be broken into smaller tasks. An agent performs best on S and M tasks.
+
+**When to break a task down further:**
+- It would take more than one focused session (roughly 2+ hours of agent work)
+- You cannot describe the acceptance criteria in 3 or fewer bullet points
+- It touches two or more independent subsystems (e.g., auth and billing)
+- You find yourself writing "and" in the task title (a sign it is two tasks)
+
+## Plan Document Template
+
+```markdown
+# Implementation Plan: [Feature/Project Name]
+
+## Overview
+[One paragraph summary of what we're building]
+
+## Architecture Decisions
+- [Key decision 1 and rationale]
+- [Key decision 2 and rationale]
+
+## Task List
+
+### Phase 1: Foundation
+- [ ] Task 1: ...
+- [ ] Task 2: ...
+
+### Checkpoint: Foundation
+- [ ] Tests pass, builds clean
+
+### Phase 2: Core Features
+- [ ] Task 3: ...
+- [ ] Task 4: ...
+
+### Checkpoint: Core Features
+- [ ] End-to-end flow works
+
+### Phase 3: Polish
+- [ ] Task 5: ...
+- [ ] Task 6: ...
+
+### Checkpoint: Complete
+- [ ] All acceptance criteria met
+- [ ] Ready for review
+
+## Risks and Mitigations
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| [Risk] | [High/Med/Low] | [Strategy] |
+
+## Open Questions
+- [Question needing human input]
+```
+
+## Parallelization Opportunities
+
+When multiple agents or sessions are available:
+
+- **Safe to parallelize:** Independent feature slices, tests for already-implemented features, documentation
+- **Must be sequential:** Database migrations, shared state changes, dependency chains
+- **Needs coordination:** Features that share an API contract (define the contract first, then parallelize)
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "I'll figure it out as I go" | That's how you end up with a tangled mess and rework. 10 minutes of planning saves hours. |
+| "The tasks are obvious" | Write them down anyway. Explicit tasks surface hidden dependencies and forgotten edge cases. |
+| "Planning is overhead" | Planning is the task. Implementation without a plan is just typing. |
+| "I can hold it all in my head" | Context windows are finite. Written plans survive session boundaries and compaction. |
+
+## Red Flags
+
+- Starting implementation without a written task list
+- Tasks that say "implement the feature" without acceptance criteria
+- No verification steps in the plan
+- All tasks are XL-sized
+- No checkpoints between tasks
+- Dependency order isn't considered
+
+## Verification
+
+Before starting implementation, confirm:
+
+- [ ] Every task has acceptance criteria
+- [ ] Every task has a verification step
+- [ ] Task dependencies are identified and ordered correctly
+- [ ] No task touches more than ~5 files
+- [ ] Checkpoints exist between major phases
+- [ ] The human has reviewed and approved the plan

claude_kit/_payload/skills/playwright-verification/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: playwright-verification
+description: Run E2E tests after deployment to verify page loads, navigation flows, user interactions, and cross-browser compatibility using the project's E2E framework.
+argument-hint: [page route, "smoke", "all", or "cross-browser"]
+disable-model-invocation: true
+---
+
+Run E2E verification for: $ARGUMENTS.
+
+## Steps
+
+1. **Determine test scope**: Based on `$ARGUMENTS`, select the test scope according to the project's E2E framework configuration. Common patterns:
+
+   | Argument | Scope | Example Command Pattern |
+   |----------|-------|------------------------|
+   | `smoke` | All smoke tests | Run smoke test suite |
+   | `all` | All E2E tests | Run all E2E tests |
+   | `cross-browser` | All tests on multiple browsers | Run tests on Chromium + Firefox + WebKit |
+   | `/route` | Tests for a specific page | Run tests for a specific route |
+   | `mobile` | Mobile viewport tests | Run mobile-specific tests |
+
+2. **Ensure dev server is running**: Check if the app is running at the configured URL (e.g., `http://localhost:5173`, `http://localhost:3000`, `http://localhost:8000`). If not, start it according to the project's setup.
+
+3. **Run the tests**: Execute the project's E2E test suite with the selected scope.
+
+4. **If writing new tests**, follow these conventions:
+
+   ### Test File Structure (Example Pattern)
+   ```typescript
+   // Example using Playwright syntax - adapt to project's E2E framework
+   import { test, expect } from '@playwright/test';
+
+   test.describe('Page Name', () => {
+     test.beforeEach(async ({ page }) => {
+       await page.goto('/route');
+     });
+
+     test('loads successfully', async ({ page }) => {
+       await expect(page.locator('main#main-content')).toBeVisible();
+     });
+
+     test('displays key content', async ({ page }) => {
+       await expect(page.getByRole('heading', { name: 'Page Title' })).toBeVisible();
+     });
+
+     test('navigation works', async ({ page }) => {
+       await page.click('a[href="/next-page"]');
+       await expect(page).toHaveURL('/next-page');
+     });
+
+     test('user interaction flow', async ({ page }) => {
+       await page.getByRole('button', { name: 'Action' }).click();
+       await expect(page.getByText('Result')).toBeVisible();
+     });
+   });
+   ```
+
+   ### Selector Priority (Accessibility-First)
+   | Priority | Selector Type | Example |
+   |----------|---------------|---------|
+   | 1 | Role-based | `getByRole('button', { name: 'Submit' })` |
+   | 2 | Text content | `getByText('Exception #1234')` |
+   | 3 | Label association | `getByLabel('Search')` |
+   | 4 | Placeholder | `getByPlaceholder('Filter by name')` |
+   | 5 | Test IDs | `[data-testid="metric-card"]` |
+   | 6 | CSS/XPath | `main#main-content` (last resort) |
+
+   ### Page Object Model (for complex pages)
+   ```typescript
+   // Example using Playwright - adapt to project's framework
+   import { Page, Locator, expect } from '@playwright/test';
+
+   export class DashboardPage {
+     readonly page: Page;
+     readonly heading: Locator;
+     readonly metricCards: Locator;
+     readonly sidebar: Locator;
+
+     constructor(page: Page) {
+       this.page = page;
+       this.heading = page.getByRole('heading', { level: 1 });
+       this.metricCards = page.locator('[data-testid="metric-card"]');
+       this.sidebar = page.locator('aside');
+     }
+
+     async goto() {
+       await this.page.goto('/');
+       await expect(this.page.locator('main#main-content')).toBeVisible();
+     }
+
+     async getMetricCount() {
+       return this.metricCards.count();
+     }
+
+     async navigateTo(route: string) {
+       await this.page.click(`a[href="${route}"]`);
+       await expect(this.page).toHaveURL(route);
+     }
+   }
+   ```
+
+5. **Check test results**: Review the output for failures.
+
+   ### On Failure
+   - Read the error message and trace
+   - Open the test framework's report viewer (e.g., HTML report)
+   - Check the trace viewer for step-by-step screenshots/recordings
+   - Fix the issue in the application code (not by weakening the test)
+
+6. **Report results**: Output a summary table:
+
+   | Test Suite | Passed | Failed | Skipped | Duration |
+   |-----------|--------|--------|---------|----------|
+
+   For failures:
+   | Test | Error | File:Line | Suggested Fix |
+   |------|-------|-----------|---------------|
+
+## Test Categories
+
+### Smoke Tests
+Every route loads without errors:
+- Main content is visible
+- No console errors
+- Navigation works
+- Critical user paths complete
+
+### Page Tests
+Feature-specific user flows:
+- Key content renders
+- Filters and search work
+- Interactive elements respond correctly
+- Data displays correctly
+
+### Cross-Cutting Tests
+- User state changes (e.g., persona/role switching) update the view
+- Global filters update data across pages
+- Responsive behavior at key breakpoints
+- Authentication flows
+- Error states
+
+## E2E Framework Config Reference
+
+Example configuration (adapt to project's framework):
+
+```typescript
+// Example using Playwright - adapt as needed
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './e2e',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 1 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: [['html'], ['list']],
+  use: {
+    baseURL: 'http://localhost:5173', // Adjust to project's dev server
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+  },
+  projects: [
+    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
+    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
+    { name: 'mobile-chrome', use: { ...devices['Pixel 5'] } },
+    { name: 'mobile-safari', use: { ...devices['iPhone 13'] } },
+    { name: 'tablet', use: { ...devices['iPad (gen 7)'] } },
+  ],
+  webServer: {
+    command: 'npm run dev', // Adjust to project's dev command
+    url: 'http://localhost:5173', // Adjust to project's dev server
+    reuseExistingServer: !process.env.CI,
+  },
+});
+```
+
+## E2E Directory Structure Example
+
+```
+e2e/
+  smoke.spec.ts                # Smoke tests covering all routes
+  pages/
+    dashboard.spec.ts          # Page-specific tests
+    feature-a.spec.ts
+    feature-b.spec.ts
+    models/
+      DashboardPage.ts         # Page Object Models
+      FeatureAPage.ts
+  cross-cutting/
+    auth.spec.ts               # Authentication flows
+    responsive.spec.ts         # Responsive behavior tests
+    navigation.spec.ts         # Global navigation tests
+  fixtures/
+    test-helpers.ts            # Shared test utilities
+```
+
+## Route Organization
+
+Structure E2E tests to match the application's route hierarchy. Identify critical user paths and create dedicated test suites for:
+- Landing/dashboard pages
+- Primary features (list, detail, create, edit flows)
+- Admin/settings pages
+- Authentication/authorization flows
+- Error and empty states