create-claudecraft 1.0.0

package/templates/skills/design/testing-patterns/SKILL.md

@@ -0,0 +1,276 @@
+---
+name: testing-patterns
+description: Vitest and React Testing Library patterns for React applications. Use when writing unit tests, creating test factories, or following TDD workflow. Triggers on tasks involving tests, testing, Vitest, describe/it blocks, or test-driven development.
+---
+
+# Testing Patterns
+
+## Setup Requirements
+
+This template uses Vitest with React Testing Library. Dependencies are pre-installed:
+
+```json
+{
+  "devDependencies": {
+    "@testing-library/react": "^16.0.1",
+    "@testing-library/jest-dom": "^6.6.2",
+    "vitest": "^2.1.4"
+  },
+  "scripts": {
+    "test": "vitest",
+    "test:coverage": "vitest run --coverage"
+  }
+}
+```
+
+---
+
+## TDD Workflow
+
+### Red-Green-Refactor Cycle
+
+1. **RED:** Write failing test first
+   ```tsx
+   it('renders button with correct text', () => {
+     render(<Button>Click me</Button>);
+     expect(screen.getByRole('button')).toHaveTextContent('Click me');
+   });
+   // ❌ Test fails - component doesn't exist yet
+   ```
+
+2. **GREEN:** Write minimal code to pass
+   ```tsx
+   export function Button({ children }) {
+     return <button>{children}</button>;
+   }
+   // ✅ Test passes
+   ```
+
+3. **REFACTOR:** Improve without changing behavior
+   ```tsx
+   // Add styling while keeping tests passing
+   ```
+
+---
+
+## Test Utilities
+
+### Custom Render with Providers
+
+```tsx
+// src/test-utils.tsx
+import { render, RenderOptions } from '@testing-library/react';
+import { ReactElement } from 'react';
+import { ThemeProvider } from '@/context/ThemeContext';
+
+function AllProviders({ children }: { children: React.ReactNode }) {
+  return <ThemeProvider>{children}</ThemeProvider>;
+}
+
+export function renderWithProviders(
+  ui: ReactElement,
+  options?: Omit<RenderOptions, 'wrapper'>
+) {
+  return render(ui, { wrapper: AllProviders, ...options });
+}
+
+export * from '@testing-library/react';
+export { renderWithProviders as render };
+```
+
+### Factory Functions
+
+```tsx
+// src/test-factories.ts
+
+// Props Factory for Components
+export function createButtonProps(
+  overrides: Partial<React.ComponentProps<typeof Button>> = {}
+) {
+  return {
+    children: 'Click me',
+    onClick: vi.fn(),
+    variant: 'primary' as const,
+    disabled: false,
+    ...overrides,
+  };
+}
+
+// Data Factory
+export function createUser(overrides: Partial<User> = {}): User {
+  return {
+    id: 'user-1',
+    name: 'Test User',
+    email: 'test@example.com',
+    ...overrides,
+  };
+}
+```
+
+---
+
+## Component Testing Patterns
+
+### Testing User Interactions
+
+```tsx
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+describe('Button', () => {
+  it('calls onClick when clicked', async () => {
+    const user = userEvent.setup();
+    const onClick = vi.fn();
+
+    render(<Button onClick={onClick}>Click</Button>);
+    await user.click(screen.getByRole('button'));
+
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not call onClick when disabled', async () => {
+    const user = userEvent.setup();
+    const onClick = vi.fn();
+
+    render(<Button disabled onClick={onClick}>Click</Button>);
+    await user.click(screen.getByRole('button'));
+
+    expect(onClick).not.toHaveBeenCalled();
+  });
+});
+```
+
+### Testing Accessibility
+
+```tsx
+describe('Button accessibility', () => {
+  it('decorative elements are hidden from screen readers', () => {
+    const { container } = render(<Button>Accessible</Button>);
+    const decorativeElements = container.querySelectorAll('[aria-hidden="true"]');
+
+    decorativeElements.forEach(el => {
+      expect(el).toHaveAttribute('aria-hidden', 'true');
+    });
+  });
+
+  it('button is keyboard accessible', () => {
+    render(<Button>Click</Button>);
+    const button = screen.getByRole('button');
+    button.focus();
+    expect(document.activeElement).toBe(button);
+  });
+
+  it('disabled button is not interactive', () => {
+    render(<Button disabled>Disabled</Button>);
+    const button = screen.getByRole('button');
+    expect(button).toBeDisabled();
+  });
+});
+```
+
+---
+
+## Mocking Patterns
+
+### Mocking Components
+
+```tsx
+vi.mock('@/components/ui/Button', () => ({
+  Button: ({ children, onClick }: any) => (
+    <button onClick={onClick} data-testid="mock-button">
+      {children}
+    </button>
+  ),
+}));
+```
+
+### Mocking Animations
+
+```tsx
+// Disable animations in tests
+beforeAll(() => {
+  vi.useFakeTimers();
+});
+
+afterAll(() => {
+  vi.useRealTimers();
+});
+
+it('completes animation', () => {
+  render(<AnimatedComponent />);
+  vi.advanceTimersByTime(500); // Skip 500ms animation
+  expect(screen.getByText('Done')).toBeInTheDocument();
+});
+```
+
+---
+
+## Query Priority
+
+Use queries in this order (most to least preferred):
+
+1. **`getByRole`** - Accessible elements
+   ```tsx
+   screen.getByRole('button', { name: 'Submit' })
+   ```
+
+2. **`getByLabelText`** - Form elements
+   ```tsx
+   screen.getByLabelText('Email')
+   ```
+
+3. **`getByText`** - Text content
+   ```tsx
+   screen.getByText('Welcome')
+   ```
+
+4. **`getByTestId`** - Last resort
+   ```tsx
+   screen.getByTestId('custom-element')
+   ```
+
+---
+
+## Anti-Patterns
+
+### ❌ Testing Implementation Details
+```tsx
+// BAD: Tests internal state
+expect(component.state.isHovered).toBe(true);
+
+// GOOD: Tests visible behavior
+await user.hover(button);
+expect(button).toHaveClass('hover-state');
+```
+
+### ❌ Snapshot Overuse
+```tsx
+// BAD: Entire component snapshot
+expect(container).toMatchSnapshot();
+
+// GOOD: Targeted assertion
+expect(button).toHaveClass('btn-primary');
+```
+
+### ❌ Manual Data Creation
+```tsx
+// BAD: Hardcoded in every test
+const user = { id: '1', name: 'Test', ... };
+
+// GOOD: Use factory
+const user = createUser({ name: 'Custom' });
+```
+
+---
+
+## File Organization
+
+```
+src/
+├── components/
+│   └── ui/
+│       ├── Button.tsx
+│       └── Button.test.tsx    # Tests live next to components
+├── test-utils.tsx             # Custom render with providers
+└── test-factories.ts          # Data factories
+```

package/templates/skills/design/ui-skills/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: ui-skills
+description: Opinionated constraints for building better interfaces with agents.
+---
+
+# UI Skills
+
+When invoked, apply these opinionated constraints for building better interfaces.
+
+## How to use
+
+- `/ui-skills`
+  Apply these constraints to any UI work in this conversation.
+
+- `/ui-skills <file>`
+  Review the file against all constraints below and output:
+  - violations (quote the exact line/snippet)
+  - why it matters (1 short sentence)
+  - a concrete fix (code-level suggestion)
+
+## Stack
+
+- MUST use Tailwind CSS defaults unless custom values already exist or are explicitly requested
+- MUST use `motion/react` (formerly `framer-motion`) when JavaScript animation is required
+- SHOULD use `tw-animate-css` for entrance and micro-animations in Tailwind CSS
+- MUST use `cn` utility (`clsx` + `tailwind-merge`) for class logic
+
+## Components
+
+- MUST use accessible component primitives for anything with keyboard or focus behavior (`Base UI`, `React Aria`, `Radix`)
+- MUST use the project's existing component primitives first
+- NEVER mix primitive systems within the same interaction surface
+- SHOULD prefer [`Base UI`](https://base-ui.com/react/components) for new primitives if compatible with the stack
+- MUST add an `aria-label` to icon-only buttons
+- NEVER rebuild keyboard or focus behavior by hand unless explicitly requested
+
+## Interaction
+
+- MUST use an `AlertDialog` for destructive or irreversible actions
+- SHOULD use structural skeletons for loading states
+- NEVER use `h-screen`, use `h-dvh`
+- MUST respect `safe-area-inset` for fixed elements
+- MUST show errors next to where the action happens
+- NEVER block paste in `input` or `textarea` elements
+
+## Animation
+
+- NEVER add animation unless it is explicitly requested
+- MUST animate only compositor props (`transform`, `opacity`)
+- NEVER animate layout properties (`width`, `height`, `top`, `left`, `margin`, `padding`)
+- SHOULD avoid animating paint properties (`background`, `color`) except for small, local UI (text, icons)
+- SHOULD use `ease-out` on entrance
+- NEVER exceed `200ms` for interaction feedback
+- MUST pause looping animations when off-screen
+- SHOULD respect `prefers-reduced-motion`
+- NEVER introduce custom easing curves unless explicitly requested
+- SHOULD avoid animating large images or full-screen surfaces
+
+## Typography
+
+- MUST use `text-balance` for headings and `text-pretty` for body/paragraphs
+- MUST use `tabular-nums` for data
+- SHOULD use `truncate` or `line-clamp` for dense UI
+- NEVER modify `letter-spacing` (`tracking-*`) unless explicitly requested
+
+## Layout
+
+- MUST use a fixed `z-index` scale (no arbitrary `z-*`)
+- SHOULD use `size-*` for square elements instead of `w-*` + `h-*`
+
+## Performance
+
+- NEVER animate large `blur()` or `backdrop-filter` surfaces
+- NEVER apply `will-change` outside an active animation
+- NEVER use `useEffect` for anything that can be expressed as render logic
+
+## Design
+
+- NEVER use gradients unless explicitly requested
+- NEVER use purple or multicolor gradients
+- NEVER use glow effects as primary affordances
+- SHOULD use Tailwind CSS default shadow scale unless explicitly requested
+- MUST give empty states one clear next action
+- SHOULD limit accent color usage to one per view
+- SHOULD use existing theme or Tailwind CSS color tokens before introducing new ones

package/templates/skills/design/visual-iteration/SKILL.md

@@ -0,0 +1,88 @@
+# Visual Iteration Skill
+
+Use this skill when implementing designs from mockups or iterating on visual output.
+
+## Trigger
+
+Use when user:
+- Shares a screenshot or design mockup
+- Asks to "implement this design"
+- Wants to iterate on visual appearance
+- Says "this doesn't look right"
+
+## Process
+
+### Phase 1: Analyze Reference
+
+When given a visual reference:
+
+1. **Describe what you see** (verify understanding)
+   - Layout structure
+   - Spacing patterns
+   - Typography choices
+   - Color usage
+   - Visual hierarchy
+
+2. **Ask clarifying questions** if needed
+   - "Should this match exactly or capture the style?"
+   - "Any elements to skip or modify for our context?"
+
+### Phase 2: Implement
+
+1. Generate code using project's design system
+2. Prefer DaisyUI classes over custom CSS
+3. Use Tailwind utilities for fine-tuning
+4. Keep code minimal—don't over-engineer
+
+### Phase 3: Review Cycle
+
+After implementation:
+
+```
+I've implemented the design. To continue iterating:
+
+1. Take a screenshot of the result
+2. Paste it here
+3. Tell me what to adjust
+
+Common adjustments:
+- "More spacing between X and Y"
+- "Make the heading larger"
+- "The colors feel off—try darker background"
+- "Align this to the left"
+```
+
+## Best Practices
+
+### DO
+- Reference specific measurements ("add 16px gap")
+- Compare to the original ("match the border radius from the mockup")
+- Work in small increments
+- Use semantic color names from the design system
+
+### DON'T
+- Guess at values—ask if unsure
+- Add features not in the design
+- Over-complicate with unnecessary abstractions
+- Ignore the existing component patterns
+
+## Iteration Prompts
+
+Helpful prompts for the user:
+
+```
+"The spacing feels cramped—add more breathing room"
+"Make the text hierarchy clearer"
+"This button should stand out more"
+"Match the rounded corners from my mockup"
+"The alignment is off on mobile"
+```
+
+## Output
+
+After each iteration:
+- Show the specific changes made
+- Note any assumptions
+- Ask if ready to commit or continue iterating
+
+Typical cycle: 2-3 iterations to match a design.

package/templates/skills/workflow/brainstorming/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: brainstorming
+description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation."
+---
+
+# Brainstorming Ideas Into Designs
+
+## Overview
+
+Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
+
+Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design in small sections (200-300 words), checking after each section whether it looks right so far.
+
+## The Process
+
+**Understanding the idea:**
+- Check out the current project state first (files, docs, recent commits)
+- Ask questions one at a time to refine the idea
+- Prefer multiple choice questions when possible, but open-ended is fine too
+- Only one question per message - if a topic needs more exploration, break it into multiple questions
+- Focus on understanding: purpose, constraints, success criteria
+
+**Exploring approaches:**
+- Propose 2-3 different approaches with trade-offs
+- Present options conversationally with your recommendation and reasoning
+- Lead with your recommended option and explain why
+
+**Presenting the design:**
+- Once you believe you understand what you're building, present the design
+- Break it into sections of 200-300 words
+- Ask after each section whether it looks right so far
+- Cover: architecture, components, data flow, error handling, testing
+- Be ready to go back and clarify if something doesn't make sense
+
+## After the Design
+
+**Documentation:**
+- Write the validated design to `docs/plans/YYYY-MM-DD-<topic>-design.md`
+- Use elements-of-style:writing-clearly-and-concisely skill if available
+- Commit the design document to git
+
+**Implementation (if continuing):**
+- Ask: "Ready to set up for implementation?"
+- Use superpowers:using-git-worktrees to create isolated workspace
+- Use superpowers:writing-plans to create detailed implementation plan
+
+## Key Principles
+
+- **One question at a time** - Don't overwhelm with multiple questions
+- **Multiple choice preferred** - Easier to answer than open-ended when possible
+- **YAGNI ruthlessly** - Remove unnecessary features from all designs
+- **Explore alternatives** - Always propose 2-3 approaches before settling
+- **Incremental validation** - Present design in sections, validate each
+- **Be flexible** - Go back and clarify when something doesn't make sense

package/templates/skills/workflow/dispatching-parallel-agents/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: dispatching-parallel-agents
+description: Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies
+---
+
+# Dispatching Parallel Agents
+
+## Overview
+
+When you have multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each investigation is independent and can happen in parallel.
+
+**Core principle:** Dispatch one agent per independent problem domain. Let them work concurrently.
+
+## When to Use
+
+```dot
+digraph when_to_use {
+    "Multiple failures?" [shape=diamond];
+    "Are they independent?" [shape=diamond];
+    "Single agent investigates all" [shape=box];
+    "One agent per problem domain" [shape=box];
+    "Can they work in parallel?" [shape=diamond];
+    "Sequential agents" [shape=box];
+    "Parallel dispatch" [shape=box];
+
+    "Multiple failures?" -> "Are they independent?" [label="yes"];
+    "Are they independent?" -> "Single agent investigates all" [label="no - related"];
+    "Are they independent?" -> "Can they work in parallel?" [label="yes"];
+    "Can they work in parallel?" -> "Parallel dispatch" [label="yes"];
+    "Can they work in parallel?" -> "Sequential agents" [label="no - shared state"];
+}
+```
+
+**Use when:**
+- 3+ test files failing with different root causes
+- Multiple subsystems broken independently
+- Each problem can be understood without context from others
+- No shared state between investigations
+
+**Don't use when:**
+- Failures are related (fix one might fix others)
+- Need to understand full system state
+- Agents would interfere with each other
+
+## The Pattern
+
+### 1. Identify Independent Domains
+
+Group failures by what's broken:
+- File A tests: Tool approval flow
+- File B tests: Batch completion behavior
+- File C tests: Abort functionality
+
+Each domain is independent - fixing tool approval doesn't affect abort tests.
+
+### 2. Create Focused Agent Tasks
+
+Each agent gets:
+- **Specific scope:** One test file or subsystem
+- **Clear goal:** Make these tests pass
+- **Constraints:** Don't change other code
+- **Expected output:** Summary of what you found and fixed
+
+### 3. Dispatch in Parallel
+
+```typescript
+// In Claude Code / AI environment
+Task("Fix agent-tool-abort.test.ts failures")
+Task("Fix batch-completion-behavior.test.ts failures")
+Task("Fix tool-approval-race-conditions.test.ts failures")
+// All three run concurrently
+```
+
+### 4. Review and Integrate
+
+When agents return:
+- Read each summary
+- Verify fixes don't conflict
+- Run full test suite
+- Integrate all changes
+
+## Agent Prompt Structure
+
+Good agent prompts are:
+1. **Focused** - One clear problem domain
+2. **Self-contained** - All context needed to understand the problem
+3. **Specific about output** - What should the agent return?
+
+```markdown
+Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts:
+
+1. "should abort tool with partial output capture" - expects 'interrupted at' in message
+2. "should handle mixed completed and aborted tools" - fast tool aborted instead of completed
+3. "should properly track pendingToolCount" - expects 3 results but gets 0
+
+These are timing/race condition issues. Your task:
+
+1. Read the test file and understand what each test verifies
+2. Identify root cause - timing issues or actual bugs?
+3. Fix by:
+   - Replacing arbitrary timeouts with event-based waiting
+   - Fixing bugs in abort implementation if found
+   - Adjusting test expectations if testing changed behavior
+
+Do NOT just increase timeouts - find the real issue.
+
+Return: Summary of what you found and what you fixed.
+```
+
+## Common Mistakes
+
+**❌ Too broad:** "Fix all the tests" - agent gets lost
+**✅ Specific:** "Fix agent-tool-abort.test.ts" - focused scope
+
+**❌ No context:** "Fix the race condition" - agent doesn't know where
+**✅ Context:** Paste the error messages and test names
+
+**❌ No constraints:** Agent might refactor everything
+**✅ Constraints:** "Do NOT change production code" or "Fix tests only"
+
+**❌ Vague output:** "Fix it" - you don't know what changed
+**✅ Specific:** "Return summary of root cause and changes"
+
+## When NOT to Use
+
+**Related failures:** Fixing one might fix others - investigate together first
+**Need full context:** Understanding requires seeing entire system
+**Exploratory debugging:** You don't know what's broken yet
+**Shared state:** Agents would interfere (editing same files, using same resources)
+
+## Real Example from Session
+
+**Scenario:** 6 test failures across 3 files after major refactoring
+
+**Failures:**
+- agent-tool-abort.test.ts: 3 failures (timing issues)
+- batch-completion-behavior.test.ts: 2 failures (tools not executing)
+- tool-approval-race-conditions.test.ts: 1 failure (execution count = 0)
+
+**Decision:** Independent domains - abort logic separate from batch completion separate from race conditions
+
+**Dispatch:**
+```
+Agent 1 → Fix agent-tool-abort.test.ts
+Agent 2 → Fix batch-completion-behavior.test.ts
+Agent 3 → Fix tool-approval-race-conditions.test.ts
+```
+
+**Results:**
+- Agent 1: Replaced timeouts with event-based waiting
+- Agent 2: Fixed event structure bug (threadId in wrong place)
+- Agent 3: Added wait for async tool execution to complete
+
+**Integration:** All fixes independent, no conflicts, full suite green
+
+**Time saved:** 3 problems solved in parallel vs sequentially
+
+## Key Benefits
+
+1. **Parallelization** - Multiple investigations happen simultaneously
+2. **Focus** - Each agent has narrow scope, less context to track
+3. **Independence** - Agents don't interfere with each other
+4. **Speed** - 3 problems solved in time of 1
+
+## Verification
+
+After agents return:
+1. **Review each summary** - Understand what changed
+2. **Check for conflicts** - Did agents edit same code?
+3. **Run full suite** - Verify all fixes work together
+4. **Spot check** - Agents can make systematic errors
+
+## Real-World Impact
+
+From debugging session (2025-10-03):
+- 6 failures across 3 files
+- 3 agents dispatched in parallel
+- All investigations completed concurrently
+- All fixes integrated successfully
+- Zero conflicts between agent changes