swe-workflow-skills 0.1.0

package/skills/frontend-architecture/evals/evals.json

@@ -0,0 +1,34 @@
+{
+  "skill_name": "frontend-architecture",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I'm starting a new React app (Next.js) for a project management tool. It has projects, tasks, team members, and a dashboard. Users can filter, sort, and search tasks. There's real-time collaboration. Help me design the frontend architecture.",
+      "expected_output": "Should design component hierarchy, choose state management strategy (server state vs client state), define data fetching patterns, propose folder structure, and address real-time needs.",
+      "assertions": [
+        "Decomposes UI into page, feature, UI, and layout component categories",
+        "Separates server state (TanStack Query) from client state (useState/Zustand)",
+        "Addresses real-time data with WebSocket + cache invalidation strategy",
+        "Proposes feature-based folder structure (not type-based)",
+        "Defines design tokens for visual consistency",
+        "Addresses code splitting at route level",
+        "Error boundary strategy at feature boundaries",
+        "URL state for filters, sort, and search (shareable links)"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Our React app has grown to 200+ components and state management is a mess — we have Redux, Context, local state, and even some global variables. Some components re-render 50+ times when you type in a search box. How do we untangle this?",
+      "expected_output": "Should diagnose the root causes (mixed state paradigms, no separation of server vs client state, over-connected Redux), and propose an incremental migration strategy.",
+      "assertions": [
+        "Diagnoses the re-render problem as likely unnecessary Redux subscriptions",
+        "Recommends migrating server data OUT of Redux into TanStack Query / SWR",
+        "Recommends keeping Redux only for genuinely global client state",
+        "Suggests an incremental migration (one feature at a time, not big-bang)",
+        "Applies the state placement ladder (useState first, then up)",
+        "Does NOT recommend adding yet another state management library on top",
+        "Addresses the performance issue specifically (memoization, selector optimization)"
+      ]
+    }
+  ]
+}

package/skills/frontend-architecture/references/component-patterns.md

@@ -0,0 +1,264 @@
+# Component Patterns
+
+## Contents
+- Component API design
+- Composition patterns
+- State management decision guide
+- Data fetching patterns
+- Error boundary strategy
+- Performance patterns
+
+## Component API Design
+
+### Props design rules
+
+1. **Prefer fewer, focused props** over many configurational ones.
+   Bad: `<Button size="lg" variant="primary" isLoading isDisabled rounded fullWidth />`
+   Better: Compose smaller components or use variants.
+
+2. **Use TypeScript interfaces** with explicit optional markers.
+   ```typescript
+   interface ButtonProps {
+     children: React.ReactNode;
+     variant?: 'primary' | 'secondary' | 'ghost';
+     size?: 'sm' | 'md' | 'lg';
+     disabled?: boolean;
+     loading?: boolean;
+     onClick?: () => void;
+   }
+   ```
+
+3. **Extend native HTML elements** for wrapper components.
+   ```typescript
+   interface InputProps extends React.InputHTMLAttributes<HTMLInputElement> {
+     label: string;
+     error?: string;
+   }
+   ```
+   This automatically supports all native input props without listing them.
+
+4. **Use `children` for content, not props.**
+   Bad: `<Card title="Hello" description="World" />`
+   Better: `<Card><Card.Title>Hello</Card.Title><Card.Body>World</Card.Body></Card>`
+
+5. **Don't pass components as string names.**
+   Bad: `<Icon name="arrow-right" />`
+   Better: `<Icon as={ArrowRightIcon} />` or `<ArrowRightIcon />`
+
+## Composition Patterns
+
+### Compound Components
+Components that work together, sharing implicit state through Context:
+
+```typescript
+const Tabs = ({ children, defaultValue }) => {
+  const [active, setActive] = useState(defaultValue);
+  return (
+    <TabsContext.Provider value={{ active, setActive }}>
+      {children}
+    </TabsContext.Provider>
+  );
+};
+
+Tabs.List = ({ children }) => <div role="tablist">{children}</div>;
+Tabs.Tab = ({ value, children }) => {
+  const { active, setActive } = useTabsContext();
+  return (
+    <button role="tab" aria-selected={active === value} onClick={() => setActive(value)}>
+      {children}
+    </button>
+  );
+};
+Tabs.Panel = ({ value, children }) => {
+  const { active } = useTabsContext();
+  return active === value ? <div role="tabpanel">{children}</div> : null;
+};
+
+// Usage — clean, readable, flexible
+<Tabs defaultValue="general">
+  <Tabs.List>
+    <Tabs.Tab value="general">General</Tabs.Tab>
+    <Tabs.Tab value="security">Security</Tabs.Tab>
+  </Tabs.List>
+  <Tabs.Panel value="general">General settings...</Tabs.Panel>
+  <Tabs.Panel value="security">Security settings...</Tabs.Panel>
+</Tabs>
+```
+
+Use compound components for: tabs, accordions, menus, selects, form groups.
+
+### Render Props / Children as Function
+When a component needs to share computed state with its children:
+
+```typescript
+<Fetch url="/api/users">
+  {({ data, loading, error }) => {
+    if (loading) return <Skeleton />;
+    if (error) return <ErrorMessage error={error} />;
+    return <UserList users={data} />;
+  }}
+</Fetch>
+```
+
+Modern alternative: Custom hooks usually replace render props:
+```typescript
+const { data, loading, error } = useFetch('/api/users');
+```
+
+### Slot Pattern (Layout Components)
+```typescript
+function PageLayout({ header, sidebar, children, footer }) {
+  return (
+    <div className="grid grid-cols-[250px_1fr] grid-rows-[auto_1fr_auto]">
+      <header className="col-span-2">{header}</header>
+      <aside>{sidebar}</aside>
+      <main>{children}</main>
+      <footer className="col-span-2">{footer}</footer>
+    </div>
+  );
+}
+```
+
+## State Management Decision Guide
+
+### When to use what
+
+```
+Is the state only used in one component?
+  → YES: useState
+  
+Is the state shared between parent and 1-2 children?
+  → YES: Lift state to parent, pass via props
+  
+Is it being drilled through 3+ levels?
+  → Is it rarely changing (theme, locale, auth)?
+    → YES: React Context
+  → Is it frequently changing?
+    → Is it server data (from an API)?
+      → YES: TanStack Query / SWR
+    → Is it form data?
+      → YES: React Hook Form (local to form)
+    → Is it shared client state?
+      → YES: Zustand (simple) or Redux Toolkit (complex/team)
+
+Should it survive page navigation?
+  → YES: URL search params (filters, pagination, sort)
+
+Should it survive page refresh?
+  → YES: URL params (shareable) or localStorage (personal preferences)
+```
+
+### Server state vs client state
+
+This is the most important distinction. **Don't put server data in Redux/Zustand.**
+
+**Server state** (data from your API):
+- Has a source of truth on the server
+- Can become stale
+- Needs refetching, caching, and invalidation
+- Examples: user profile, order list, product catalog
+- Tool: TanStack Query, SWR, RTK Query
+
+**Client state** (exists only in the browser):
+- Has no server counterpart
+- Is always "fresh" by definition
+- Examples: sidebar open/closed, selected tab, modal visibility, dark mode
+- Tool: useState, Context, Zustand
+
+## Data Fetching Patterns
+
+### TanStack Query (recommended for most apps)
+
+```typescript
+// Define the query
+function useProjects() {
+  return useQuery({
+    queryKey: ['projects'],
+    queryFn: () => api.get('/projects'),
+    staleTime: 5 * 60 * 1000, // Consider data fresh for 5 minutes
+  });
+}
+
+// Use in component — loading/error/data handled automatically
+function ProjectList() {
+  const { data: projects, isLoading, error } = useProjects();
+  if (isLoading) return <Skeleton />;
+  if (error) return <ErrorMessage error={error} />;
+  return <List items={projects} />;
+}
+
+// Mutations with optimistic updates
+function useDeleteProject() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: (id) => api.delete(`/projects/${id}`),
+    onMutate: async (id) => {
+      await queryClient.cancelQueries(['projects']);
+      const previous = queryClient.getQueryData(['projects']);
+      queryClient.setQueryData(['projects'], old => old.filter(p => p.id !== id));
+      return { previous };
+    },
+    onError: (err, id, context) => {
+      queryClient.setQueryData(['projects'], context.previous); // Rollback
+    },
+    onSettled: () => queryClient.invalidateQueries(['projects']),
+  });
+}
+```
+
+## Error Boundary Strategy
+
+```typescript
+// Generic error boundary
+function ErrorBoundary({ children, fallback }) {
+  return (
+    <ReactErrorBoundary
+      fallbackRender={({ error, resetErrorBoundary }) => (
+        fallback || (
+          <ErrorPanel
+            message="Something went wrong"
+            error={error}
+            onRetry={resetErrorBoundary}
+          />
+        )
+      )}
+    >
+      {children}
+    </ReactErrorBoundary>
+  );
+}
+
+// Strategy: wrap at feature boundaries, not at the app root
+<ErrorBoundary>        {/* Page-level: catches route errors */}
+  <Header />           {/* Not wrapped: if header breaks, show error */}
+  <ErrorBoundary>      {/* Feature-level: isolates sidebar failures */}
+    <Sidebar />
+  </ErrorBoundary>
+  <ErrorBoundary>      {/* Feature-level: isolates main content failures */}
+    <MainContent />
+  </ErrorBoundary>
+</ErrorBoundary>
+```
+
+Place error boundaries at **feature boundaries**, not around every component. The goal: a sidebar crash doesn't take down the whole page.
+
+## Performance Patterns
+
+### Memoization rules
+- `React.memo()`: Wrap components that receive the same props frequently but re-render anyway. Don't wrap everything — it has overhead.
+- `useMemo()`: Cache expensive computations. Not needed for simple operations.
+- `useCallback()`: Stabilize function references passed as props to memoized children.
+- **Rule of thumb**: Don't optimize until you measure a problem. Then optimize surgically.
+
+### Code splitting
+```typescript
+// Route-level splitting (always do this)
+const ProjectPage = React.lazy(() => import('./features/projects/ProjectPage'));
+const SettingsPage = React.lazy(() => import('./features/settings/SettingsPage'));
+
+// Component-level splitting (for large, rarely-used components)
+const HeavyChart = React.lazy(() => import('./components/HeavyChart'));
+```
+
+### List virtualization
+For lists over 100 items, use virtualization (react-window or TanStack Virtual) to render only visible items. Don't render 10,000 DOM nodes.

package/skills/frontend-architecture/templates/folder-structure.md

@@ -0,0 +1,203 @@
+# Frontend Architecture Templates
+
+---
+
+## Recommended `src/` Folder Structure
+
+Feature-based layout with a shared component library. Copy this structure and delete the directories you don't need yet.
+
+```
+src/
+├── app/                          # App-level wiring (not business logic)
+│   ├── providers.tsx             # All context providers composed in one place
+│   ├── router.tsx                # Route definitions
+│   └── layout.tsx                # Root layout (nav, sidebar, footer)
+│
+├── features/                     # One directory per business feature
+│   ├── auth/
+│   │   ├── components/           # Components used only in this feature
+│   │   │   └── LoginForm/
+│   │   │       ├── LoginForm.tsx
+│   │   │       ├── LoginForm.test.tsx
+│   │   │       └── LoginForm.types.ts
+│   │   ├── hooks/                # Feature-specific hooks
+│   │   │   └── useLogin.ts
+│   │   ├── api.ts                # API calls for this feature (React Query queries/mutations)
+│   │   ├── types.ts              # Types scoped to this feature
+│   │   └── index.ts              # Public API — only export what other modules need
+│   ├── projects/
+│   └── settings/
+│
+├── components/                   # Shared, reusable UI components (no business logic)
+│   ├── ui/                       # Atomic primitives: Button, Input, Modal, Badge
+│   └── layout/                   # Layout components: Stack, Grid, Container, Sidebar
+│
+├── hooks/                        # Shared hooks: useDebounce, useMediaQuery, useLocalStorage
+├── lib/                          # Shared infrastructure
+│   ├── api-client.ts             # Configured axios/fetch instance
+│   ├── tokens.ts                 # Design tokens (see below)
+│   └── utils.ts                  # Pure utility functions
+└── types/                        # Shared TypeScript types and interfaces
+```
+
+> **Rules:** Features import from `components/` and `lib/`. Features never import from other features. Circular imports mean a responsibility boundary is wrong — move the shared code to `lib/` or `components/`.
+
+---
+
+## Component File Template
+
+Co-locate everything for a component in one folder. Avoids hunting across the filesystem for related files.
+
+```
+components/ui/Button/
+├── Button.tsx         # Component implementation
+├── Button.test.tsx    # Tests
+├── Button.types.ts    # Props interface
+└── index.ts           # Re-export (allows: import { Button } from '@/components/ui/Button')
+```
+
+**Button.types.ts**
+```typescript
+export interface ButtonProps {
+  variant?: 'primary' | 'secondary' | 'ghost' | 'danger';
+  size?: 'sm' | 'md' | 'lg';
+  disabled?: boolean;
+  loading?: boolean;
+  onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void;
+  children: React.ReactNode;
+}
+```
+
+**Button.tsx**
+```tsx
+import type { ButtonProps } from './Button.types';
+
+export function Button({
+  variant = 'primary',
+  size = 'md',
+  disabled = false,
+  loading = false,
+  onClick,
+  children,
+}: ButtonProps) {
+  return (
+    <button
+      className={`btn btn--${variant} btn--${size}`}
+      disabled={disabled || loading}
+      onClick={onClick}
+    >
+      {loading ? <span className="spinner" aria-hidden /> : null}
+      {children}
+    </button>
+  );
+}
+```
+
+---
+
+## Design Tokens — `lib/tokens.ts`
+
+Define all visual constants here. Never hardcode colors, spacing, or typography values in components.
+
+```typescript
+export const tokens = {
+  color: {
+    primary: {
+      50:  '#eff6ff',
+      100: '#dbeafe',
+      500: '#3b82f6',
+      700: '#1d4ed8',
+      900: '#1e3a8a',
+    },
+    neutral: {
+      50:  '#f9fafb',
+      100: '#f3f4f6',
+      200: '#e5e7eb',
+      500: '#6b7280',
+      800: '#1f2937',
+      900: '#111827',
+    },
+    semantic: {
+      success: '#10b981',
+      warning: '#f59e0b',
+      error:   '#ef4444',
+      info:    '#3b82f6',
+    },
+  },
+  spacing: {
+    xs:  '0.25rem',   //  4px
+    sm:  '0.5rem',    //  8px
+    md:  '1rem',      // 16px
+    lg:  '1.5rem',    // 24px
+    xl:  '2rem',      // 32px
+    '2xl': '3rem',    // 48px
+  },
+  radius: {
+    sm:   '0.25rem',
+    md:   '0.5rem',
+    lg:   '1rem',
+    full: '9999px',
+  },
+  fontSize: {
+    xs:   '0.75rem',
+    sm:   '0.875rem',
+    base: '1rem',
+    lg:   '1.125rem',
+    xl:   '1.25rem',
+    '2xl': '1.5rem',
+  },
+  shadow: {
+    sm: '0 1px 2px rgba(0,0,0,0.05)',
+    md: '0 4px 6px rgba(0,0,0,0.1)',
+    lg: '0 10px 15px rgba(0,0,0,0.1)',
+  },
+} as const;
+
+// Type helpers for token-safe props
+export type ColorToken = typeof tokens.color;
+export type SpacingToken = keyof typeof tokens.spacing;
+```
+
+---
+
+## Custom Hook Template — `hooks/useResource.ts`
+
+Standard pattern for data-fetching hooks (wraps React Query; adapt for SWR or raw fetch).
+
+```typescript
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import { fetchResource, updateResource } from '@/features/resource/api';
+import type { Resource } from '@/features/resource/types';
+
+// Query key factory — keeps cache keys consistent across the app
+export const resourceKeys = {
+  all:    () => ['resources'] as const,
+  list:   (filters: Record<string, unknown>) => [...resourceKeys.all(), 'list', filters] as const,
+  detail: (id: string) => [...resourceKeys.all(), 'detail', id] as const,
+};
+
+// Fetch hook — returns { data, isLoading, error }
+export function useResource(id: string) {
+  return useQuery({
+    queryKey: resourceKeys.detail(id),
+    queryFn:  () => fetchResource(id),
+    enabled:  Boolean(id),
+    staleTime: 5 * 60 * 1000,   // 5 minutes
+  });
+}
+
+// Mutation hook — returns { mutate, isPending, error }
+export function useUpdateResource() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: ({ id, data }: { id: string; data: Partial<Resource> }) =>
+      updateResource(id, data),
+    onSuccess: (_, { id }) => {
+      // Invalidate affected queries so UI stays fresh
+      queryClient.invalidateQueries({ queryKey: resourceKeys.detail(id) });
+      queryClient.invalidateQueries({ queryKey: resourceKeys.all() });
+    },
+  });
+}
+```

package/skills/git-workflow/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: git-workflow
+description: "Write commit messages, PR descriptions, and manage branching strategy following conventional commits. Triggers: write a commit message, commit this, PR description, pull request, branching strategy, git workflow, squash commits, rebase, conventional commits, how should I commit this, review staged changes."
+model: haiku
+allowed-tools: Read, Grep, Glob, Write, Edit
+---
+
+# Git Workflow
+
+Help write clear commit messages, structured PR descriptions, and manage branching conventions. Good git history is documentation — it tells the story of why the codebase evolved the way it did.
+
+## Workflow: Commit Messages
+
+### Step 1: Analyze the Changes
+
+Read the staged changes to understand what was done:
+
+```bash
+git diff --staged
+```
+
+Identify:
+- **What changed?** (files modified, functions added/removed, logic altered)
+- **Why did it change?** (feature, bugfix, refactor, dependency update)
+- **Is this one logical change or multiple?** If multiple, suggest splitting into separate commits.
+
+### Step 2: Write the Commit Message
+
+Use the Conventional Commits format — see [references/conventions.md](references/conventions.md):
+
+```
+<type>(<scope>): <short description>
+
+<body — explain WHY, not WHAT>
+
+<footer — references, breaking changes>
+```
+
+**The subject line** (first line):
+- Type: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `perf`, `ci`, `build`
+- Scope: The module, component, or area affected (optional but recommended)
+- Description: Present tense, lowercase, no period, under 50 characters
+- It should complete the sentence: "If applied, this commit will..."
+
+**The body** (optional but valuable for non-trivial changes):
+- Explain WHY this change was made, not WHAT changed (the diff shows what)
+- Include context that isn't obvious from the code
+- Wrap at 72 characters
+
+**The footer** (optional):
+- Reference issues: `Closes #123`, `Fixes #456`
+- Breaking changes: `BREAKING CHANGE: description`
+- Co-authors: `Co-authored-by: Name <email>`
+
+### Step 3: Validate
+
+Before committing, check:
+- [ ] Is this a single logical change? (If not, split it)
+- [ ] Does the subject line describe the behavior change, not the implementation?
+- [ ] Would someone understand why this commit exists 6 months from now?
+- [ ] Are related issue numbers referenced?
+
+## Workflow: PR Descriptions
+
+### Step 1: Analyze the Branch
+
+Read the changes in the branch:
+
+```bash
+git log main..HEAD --oneline
+git diff main...HEAD --stat
+```
+
+Understand the full scope of changes across all commits.
+
+### Step 2: Write the PR Description
+
+Use the template at [templates/pull-request.md](templates/pull-request.md). Key sections:
+
+- **What**: What this PR does (1-2 sentences)
+- **Why**: Why this change is needed (link to issue/task)
+- **How**: Brief description of the approach taken and key decisions
+- **Testing**: How the changes were tested
+- **Screenshots**: For UI changes (before/after)
+- **Checklist**: Standard items (tests pass, docs updated, etc.)
+
+The PR description should let a reviewer understand the change without reading every line of code first.
+
+### Step 3: Self-Review
+
+Before requesting review:
+- [ ] Read through the entire diff one more time
+- [ ] Are there any debugging leftovers?
+- [ ] Are there any changes that don't belong in this PR?
+- [ ] Is the PR a reasonable size? (Under 400 lines changed is ideal. Over 800 is a red flag.)
+
+If the PR is too large, suggest splitting it into stacked PRs or smaller logical units.
+
+## Workflow: Branching Strategy
+
+Help set up or improve branching conventions. Ask about team size and release cadence, then recommend:
+
+**For small teams (1-5 devs) or continuous deployment:**
+- `main` — always deployable
+- `feat/description` — feature branches, short-lived (1-3 days)
+- `fix/description` — bug fix branches
+- Merge to main via PR, deploy from main
+
+**For medium teams (5-15 devs) or scheduled releases:**
+- `main` — production
+- `develop` — integration branch
+- `feat/description`, `fix/description` — branch from develop
+- `release/x.y.z` — stabilization branch before release
+- `hotfix/description` — urgent fixes branching from main
+
+**For large teams or complex release cycles:**
+- Consider trunk-based development with feature flags
+- Short-lived branches (< 1 day) merged to main
+- Feature flags control what's visible to users
+
+See [references/conventions.md](references/conventions.md) for branch naming conventions.
+
+## Principles Applied
+
+- **KISS**: One commit = one logical change. Don't bundle unrelated changes.
+- **DRY**: If you're writing the same commit message pattern repeatedly, you might be making commits too granular or too broad.
+- **Functional Independence**: Each PR should be independently deployable when possible. Avoid PRs that depend on other unmerged PRs.

package/skills/git-workflow/evals/evals.json

@@ -0,0 +1,44 @@
+{
+  "skill_name": "git-workflow",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I just finished implementing a user notification feature. I've staged all changes. Write a good commit message for me.",
+      "expected_output": "Should read the staged diff first, then write a Conventional Commits formatted message with type, scope, subject, and body explaining why.",
+      "assertions": [
+        "Runs git diff --staged to read the actual changes",
+        "Uses Conventional Commits format (type(scope): description)",
+        "Subject line is under 50 characters",
+        "Body explains WHY, not just WHAT",
+        "Checks if the staged changes are a single logical unit",
+        "If multiple logical changes, suggests splitting into separate commits"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "I need to write a PR description for a branch that adds Stripe payment integration. The branch has 12 commits including some WIP and fix-typo commits. We're using a standard PR template.",
+      "expected_output": "Should read the branch diff and commit log, suggest squashing the WIP commits, then write a structured PR description.",
+      "assertions": [
+        "Reads git log and diff for the branch",
+        "Suggests cleaning up the 'WIP' and 'fix-typo' commits via rebase/squash",
+        "Writes a complete PR description with What/Why/How/Testing sections",
+        "Links to the relevant issue or task",
+        "Includes a checklist with relevant items (especially security for payments)",
+        "Notes for reviewers highlights the payment-related security considerations"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "We're a team of 4 starting a new project. What branching strategy should we use? We deploy to production multiple times a day.",
+      "expected_output": "Should recommend a simple strategy (main + short-lived feature branches) given small team and continuous deployment. Should NOT suggest GitFlow or other complex models.",
+      "assertions": [
+        "Recommends simple branching (main + feature branches)",
+        "Does NOT recommend GitFlow (too heavy for 4 devs + continuous deployment)",
+        "Recommends short-lived branches (1-3 days max)",
+        "Suggests squash-merge as default merge strategy",
+        "Includes branch naming conventions",
+        "Mentions PR review requirements appropriate for team size"
+      ]
+    }
+  ]
+}