@jgamaraalv/ts-dev-kit 2.2.0 → 3.0.0

package/skills/generate-task/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: generate-task
+description: "Breaks a PRD into ordered, production-ready engineering tasks ready for execution by /execute-task. Use when: (1) converting a PRD document into executable engineering tasks, (2) planning feature delivery as a sequence of mergeable, self-contained pull requests, (3) the user says 'generate tasks', 'break down this PRD', 'create tasks from PRD', 'plan the implementation tasks', or 'task breakdown'. Each generated task document embeds its own success criteria, baseline checks, post-change tests, performance benchmarks, and non-functional requirements — making it directly executable by /execute-task."
+argument-hint: "[prd-file-path | task-without-context | epic-task | big-task]"
+---
+
+<prd>
+$ARGUMENTS
+</prd>
+
+<workflow>
+Follow each phase in order.
+
+<phase_1_read_prd>
+Read the PRD document fully. Extract and organize:
+- Functional requirements — numbered, atomic conditions
+- Acceptance criteria — how feature completion is verified
+- Non-functional requirements — performance, security, accessibility, scalability targets
+- Scope — what is included and what is explicitly excluded
+- User journeys — key flows and their steps
+- Success metrics and KPIs
+</phase_1_read_prd>
+
+<phase_2_analyze_codebase>
+Before decomposing tasks, understand the target project:
+1. Read CLAUDE.md and root package.json — project structure, package manager, tech stack, key directories.
+2. Identify where implementation units live — backend routes, frontend pages, shared types, database schemas, tests.
+3. Search for patterns similar to the feature being built — use Grep/Glob to find related files and establish co-location conventions.
+4. List the domain areas the feature touches — database, API, shared, frontend, tests, config.
+</phase_2_analyze_codebase>
+
+<phase_3_identify_implementation_units>
+Map every PRD requirement to concrete implementation units. An implementation unit is any atomic change: a new schema, a route, a component, a migration, a shared type, a test file, a config entry, an i18n key.
+
+For each unit, identify:
+- **File path** (exact, following codebase conventions)
+- **Action**: create or modify
+- **Domain**: database | api | shared | frontend | test | config | docs
+- **Dependencies**: which other units must exist first
+
+**Standard dependency ordering** (lower layers before higher):
+1. Shared types, constants, i18n keys, env variables
+2. Database migrations and schema updates
+3. API routes, handlers, validation schemas
+4. Shared hooks, utilities, helper functions
+5. UI components (atoms → molecules → organisms)
+6. Pages and routes composing components
+7. Tests (unit, integration, E2E)
+8. Config and infrastructure changes
+9. Documentation updates
+
+**Orphan-free rule** — every consumer of a resource must be in the same task as its producer OR in a later task that explicitly depends on the producer's task:
+- New i18n key + every component using that key → same task (or key in TASK_N, component in TASK_M where M > N and TASK_M depends on TASK_N)
+- New database column + migration that adds it → same task
+- New shared type + every immediate consumer → same task
+- New component + the page that renders it → same task (unless page is intentionally deferred to a later task)
+</phase_3_identify_implementation_units>
+
+<phase_4_group_into_tasks>
+Group implementation units into tasks. Apply these rules in order:
+
+**Rule 1 — 30-file limit**: a task may create or modify at most 30 files. If a natural group exceeds this, split on domain boundaries (data layer, API layer, UI layer, test layer).
+
+**Rule 2 — Production-ready delivery**: every task, when merged in order, must leave the application in a runnable state — no broken imports, unresolved references, orphaned i18n keys, or missing migrations.
+
+**Rule 3 — Forward dependency only**: if TASK_N requires output from TASK_M, then M < N. No task may depend on a later task.
+
+**Rule 4 — Mergeable without breaking**: use feature flags, graceful degradation, or empty-state handling so earlier tasks don't expose incomplete UX to end users.
+
+**Rule 5 — Clear value delivery**: each task must deliver a demonstrable increment — a working endpoint, a rendered component, a passing test suite. Avoid tasks with no visible or testable outcome.
+
+**Recommended grouping** (adapt per feature):
+1. **Foundation** — shared types, constants, i18n keys, env variables
+2. **Data layer** — database schema, migrations, ORM models
+3. **API layer** — routes, handlers, validation schemas, error codes
+4. **Core UI** — reusable components, hooks, state management
+5. **Feature pages** — pages and routes composing the core UI
+6. **Tests & polish** — comprehensive test suites, accessibility audit, performance tuning
+7. **Documentation** — CLAUDE.md updates, API docs, migration guides
+
+Split tasks at domain boundaries when a group would exceed 30 files.
+</phase_4_group_into_tasks>
+
+<phase_5_define_verification_criteria>
+For each task, derive its verification criteria from the PRD. These become binding requirements embedded in the task document and executed by /execute-task.
+
+**Success criteria** — select PRD acceptance criteria that apply to this task's scope. Write them as testable assertions:
+- "POST /api/resource returns 201 with the created resource payload" (not "API works")
+- "Page renders the empty state at 1440px without console errors" (not "page looks right")
+- "Migration runs cleanly on an empty database" (not "migration works")
+
+**Baseline checks** — what to capture BEFORE making changes:
+- Standard quality gates: tsc, lint, test, build (pass/fail and counts)
+- Domain-specific: API endpoints (HTTP status + timing), pages (screenshot + LCP), schema state (table columns and types)
+
+**Post-change checks** — what to verify AFTER changes, mapped 1:1 to each success criterion.
+
+**Performance benchmarks** — from PRD NFRs or domain defaults:
+- API endpoints: p95 response time target
+- Frontend pages: LCP target, bundle size delta
+- Database queries: execution time target
+
+**Non-functional requirements** — scope PRD NFRs to this task's domain:
+- Database task → data integrity, migration rollback safety, index strategy
+- API task → input validation coverage, auth guard presence, rate limiting
+- Frontend task → WCAG compliance level, responsive breakpoints, keyboard navigation
+</phase_5_define_verification_criteria>
+
+<phase_6_generate_task_documents>
+Generate a document for each task using the template from [template.md](template.md).
+
+Before saving, validate each document:
+- [ ] File count ≤ 30
+- [ ] No file path appears in more than one task
+- [ ] Every success criterion is testable (specific, measurable outcome)
+- [ ] Every "create" file has its consumer in the same or a later task
+- [ ] Task N's dependencies all have numbers < N
+- [ ] Baseline checks include at minimum: tsc, lint, test, build
+
+Fix any violation before saving.
+</phase_6_generate_task_documents>
+</workflow>
+
+<output>
+Save each task document to:
+```
+[project-root]/docs/features/[FEATURE_NAME]/TASK_[TASK_NUMBER].md
+```
+
+After saving all tasks, print a summary table:
+
+| Task | Title | Files | Depends on | Key deliverable |
+|------|-------|-------|------------|-----------------|
+| TASK_01 | ... | N files | none | ... |
+| TASK_02 | ... | N files | TASK_01 | ... |
+</output>

package/skills/generate-task/template.md

@@ -0,0 +1,71 @@
+# TASK_[N]: [Title]
+
+## Overview
+[2-3 sentences describing what this task delivers and why it is a cohesive unit
+of work. State the concrete value delivered when this task is merged.]
+
+## Dependencies
+- Requires merged: [list of TASK_X titles, or "none"]
+
+## Scope — Files (max 30)
+
+| File | Action | Purpose |
+|------|--------|---------|
+| `path/to/file.ts` | create | What this file contains |
+| `path/to/other.ts` | modify | What changes and why |
+
+**Total: N files**
+
+## Success Criteria
+
+- [ ] 1. [Testable, specific condition — maps to a PRD acceptance criterion]
+- [ ] 2. [...]
+
+## Non-functional Requirements
+
+- **Performance**: [specific targets, e.g., "p95 API response < 200ms", "LCP < 2.5s"]
+- **Security**: [e.g., "all inputs validated with zod schema", "auth guard on all routes"]
+- **Accessibility**: [for frontend tasks: WCAG level and specific requirements]
+- **Scalability**: [relevant requirements, or "n/a for this task"]
+
+## Verification Plan
+
+### Baseline Checks (run before making changes)
+
+**Quality gates:**
+- `tsc` — record pass/fail
+- `lint` — record pass/fail
+- `test` — record pass/fail + test count
+- `build` — record pass/fail + bundle size (if frontend)
+
+**Domain-specific baseline:**
+- [Example — API: `GET /api/resource` — record HTTP status and response time]
+- [Example — Frontend: navigate to `/feature-page` — capture screenshot and LCP]
+- [Example — Database: record current schema of table `users` (columns + types)]
+
+### Post-change Checks
+
+**Quality gates:** [same commands as baseline — all must pass]
+
+**Feature verification:**
+- [ ] [Check mapped 1:1 to success criterion 1 — describe exact verification steps]
+- [ ] [Check mapped 1:1 to success criterion 2]
+
+**Performance benchmarks:**
+- [metric]: target [value], acceptable range [range]
+
+### MCP Checks
+
+**If browser MCPs available (playwright / chrome-devtools):**
+- [Specific pages to navigate and screenshot]
+- [Specific user interactions to exercise]
+- [Specific performance traces to capture]
+
+**If no browser MCPs available (shell-only fallback):**
+- [What to verify via build output, curl, or CLI commands]
+
+## Implementation Notes
+
+[Optional: key constraints, patterns to follow, architectural decisions the
+executing agent should know. Reference specific file paths or conventions
+discovered from the codebase analysis.]

package/skills/owasp-security-review/SKILL.md

@@ -86,13 +86,4 @@ Use these severity levels when reporting findings:
 
 ## Output format
 
-When reporting security findings, use this structure:
-
-```
-### [SEVERITY] A0X: Category Name — Brief title
-
-**Location**: `file:line`
-**Risk**: What can go wrong and the impact.
-**Finding**: What the code does wrong.
-**Fix**: Specific remediation with code example.
-```
+When reporting security findings, use the template in [template.md](template.md) for each finding.

package/skills/owasp-security-review/template.md

@@ -0,0 +1,6 @@
+### [SEVERITY] A0X: Category Name — Brief title
+
+**Location**: `file:line`
+**Risk**: What can go wrong and the impact.
+**Finding**: What the code does wrong.
+**Fix**: Specific remediation with code example.

package/skills/tanstack-query/SKILL.md

@@ -0,0 +1,348 @@
+---
+name: tanstack-query
+description: |
+  TanStack Query v5 (React Query) reference for data fetching, caching,
+  and server state management in React. Use when: (1) writing useQuery,
+  useMutation, or useInfiniteQuery hooks, (2) setting up QueryClient
+  and queryOptions, (3) implementing optimistic updates or cache
+  invalidation, (4) configuring SSR/hydration with Next.js App Router
+  or Pages Router, (5) testing React Query hooks, (6) working with
+  TypeScript types, Suspense, or advanced patterns like dependent
+  queries and infinite scroll.
+---
+
+# TanStack Query v5 (React)
+
+## Setup
+
+```tsx
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 60 * 1000, // 1 min (default is 0)
+      gcTime: 5 * 60 * 1000, // 5 min (default)
+      retry: 3,              // 3 retries with exponential backoff (default)
+      refetchOnWindowFocus: true, // default
+    },
+  },
+})
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <YourApp />
+    </QueryClientProvider>
+  )
+}
+```
+
+## Important Defaults
+
+| Default | Value | Notes |
+|---------|-------|-------|
+| `staleTime` | `0` | Cached data is immediately stale; triggers background refetch on mount/focus/reconnect |
+| `gcTime` | `5 min` | Inactive queries garbage collected after 5 minutes |
+| `retry` | `3` (queries) / `0` (mutations) | Queries retry 3x with exponential backoff; mutations do NOT retry |
+| `refetchOnWindowFocus` | `true` | Stale queries refetch when tab regains focus |
+| `refetchOnReconnect` | `true` | Stale queries refetch when network reconnects |
+| `refetchOnMount` | `true` | Stale queries refetch when new instance mounts |
+| `structuralSharing` | `true` | Preserves referential identity if data is structurally equal |
+
+**Key recommendation:** Set `staleTime` above 0 to control refetch frequency rather than disabling individual refetch triggers.
+
+## queryOptions — co-locate key + fn
+
+Always use `queryOptions` to define query configurations. It enables type inference across `useQuery`, `prefetchQuery`, `getQueryData`, and `setQueryData`.
+
+```tsx
+import { queryOptions, infiniteQueryOptions } from '@tanstack/react-query'
+
+export function todosOptions(filters: TodoFilters) {
+  return queryOptions({
+    queryKey: ['todos', filters],
+    queryFn: () => fetchTodos(filters),
+    staleTime: 5 * 1000,
+  })
+}
+
+// Works everywhere with full type inference:
+useQuery(todosOptions({ status: 'done' }))
+useSuspenseQuery(todosOptions({ status: 'done' }))
+queryClient.prefetchQuery(todosOptions({ status: 'done' }))
+queryClient.setQueryData(todosOptions({ status: 'done' }).queryKey, newData)
+const cached = queryClient.getQueryData(todosOptions({ status: 'done' }).queryKey)
+//    ^? TodoItem[] | undefined
+```
+
+For infinite queries, use `infiniteQueryOptions` (same pattern, adds `initialPageParam` and `getNextPageParam`).
+
+## useQuery
+
+```tsx
+const {
+  data,              // TData | undefined
+  error,             // TError | null
+  status,            // 'pending' | 'error' | 'success'
+  isPending,         // no cached data yet
+  isError,
+  isSuccess,
+  isFetching,        // queryFn is running (including background refetch)
+  isLoading,         // isPending && isFetching (first load only)
+  isPlaceholderData, // showing placeholder, not real data
+  isStale,
+  refetch,
+  fetchStatus,       // 'fetching' | 'paused' | 'idle'
+} = useQuery({
+  queryKey: ['todos', userId],  // unique cache key (Array)
+  queryFn: () => fetchTodos(userId),
+  enabled: !!userId,            // disable until userId exists
+  staleTime: 60_000,
+  select: (data) => data.filter(t => !t.done), // transform/filter
+  placeholderData: keepPreviousData,            // smooth pagination
+})
+```
+
+**Query states:** `status` tells you "do we have data?"; `fetchStatus` tells you "is the queryFn running?". They are orthogonal — a query can be `pending` + `paused` (no data, no network).
+
+## Query Keys
+
+Keys must be Arrays. They are hashed deterministically.
+
+```tsx
+// Object key order does NOT matter — these are equivalent:
+useQuery({ queryKey: ['todos', { status, page }] })
+useQuery({ queryKey: ['todos', { page, status }] })
+
+// Array item order DOES matter — these are different:
+useQuery({ queryKey: ['todos', status, page] })
+useQuery({ queryKey: ['todos', page, status] })
+```
+
+**Rule:** If your queryFn depends on a variable, include it in the queryKey. The key acts as a dependency array.
+
+## useMutation
+
+```tsx
+const queryClient = useQueryClient()
+
+const mutation = useMutation({
+  mutationFn: (newTodo: CreateTodoInput) => api.post('/todos', newTodo),
+  onSuccess: (data, variables) => {
+    // Invalidate related queries to trigger refetch
+    queryClient.invalidateQueries({ queryKey: ['todos'] })
+    // Or update cache directly with response data
+    queryClient.setQueryData(['todos', data.id], data)
+  },
+  onError: (error, variables, onMutateResult) => {},
+  onSettled: (data, error, variables, onMutateResult) => {},
+})
+
+// Trigger:
+mutation.mutate({ title: 'New todo' })
+
+// Or with per-call callbacks:
+mutation.mutate(input, { onSuccess: () => navigate('/todos') })
+
+// Async variant (returns Promise):
+const data = await mutation.mutateAsync(input)
+```
+
+**Lifecycle:** `onMutate` → `mutationFn` → `onSuccess`/`onError` → `onSettled`. Callbacks returning promises are awaited.
+
+**Gotcha:** Per-call `mutate()` callbacks only fire for the *latest* call if mutations overlap. Use `useMutation`-level callbacks for reliable logic.
+
+## Query Invalidation
+
+```tsx
+// Prefix match (default) — invalidates ['todos'] and ['todos', { page: 1 }]
+queryClient.invalidateQueries({ queryKey: ['todos'] })
+
+// Exact match only
+queryClient.invalidateQueries({ queryKey: ['todos'], exact: true })
+
+// Predicate for fine-grained control
+queryClient.invalidateQueries({
+  predicate: (query) => query.queryKey[0] === 'todos' && query.queryKey[1]?.version >= 10,
+})
+
+// ALL queries
+queryClient.invalidateQueries()
+```
+
+Invalidation marks queries as stale and triggers background refetch for active (rendered) queries.
+
+## Optimistic Updates
+
+### Approach 1: Via the UI (simpler, recommended)
+
+Render optimistic state from `variables` directly in JSX:
+
+```tsx
+const { mutate, variables, isPending, isError } = useMutation({
+  mutationFn: (text: string) => api.post('/todos', { text }),
+  onSettled: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
+})
+
+// In JSX:
+{todos.map(todo => <li key={todo.id}>{todo.text}</li>)}
+{isPending && <li style={{ opacity: 0.5 }}>{variables}</li>}
+```
+
+Access pending mutations from other components with `useMutationState`:
+
+```tsx
+const pendingTodos = useMutationState<string>({
+  filters: { mutationKey: ['addTodo'], status: 'pending' },
+  select: (mutation) => mutation.state.variables,
+})
+```
+
+### Approach 2: Via cache (with rollback)
+
+```tsx
+useMutation({
+  mutationFn: updateTodo,
+  onMutate: async (newTodo, context) => {
+    await context.client.cancelQueries({ queryKey: ['todos'] })
+    const previous = context.client.getQueryData(['todos'])
+    context.client.setQueryData(['todos'], (old) => [...old, newTodo])
+    return { previous }
+  },
+  onError: (err, newTodo, onMutateResult, context) => {
+    context.client.setQueryData(['todos'], onMutateResult.previous)
+  },
+  onSettled: (data, error, variables, onMutateResult, context) => {
+    context.client.invalidateQueries({ queryKey: ['todos'] })
+  },
+})
+```
+
+**Always** `cancelQueries` before optimistic update to prevent background refetches from overwriting.
+
+## Infinite Queries
+
+```tsx
+const {
+  data,               // { pages: T[], pageParams: unknown[] }
+  fetchNextPage,
+  fetchPreviousPage,
+  hasNextPage,        // true when getNextPageParam returns non-null/undefined
+  hasPreviousPage,
+  isFetchingNextPage,
+  isFetchingPreviousPage,
+} = useInfiniteQuery({
+  queryKey: ['projects'],
+  queryFn: ({ pageParam }) => fetchProjects(pageParam),
+  initialPageParam: 0,     // REQUIRED
+  getNextPageParam: (lastPage, allPages) => lastPage.nextCursor ?? undefined,
+  maxPages: 3,             // optional: cap cached pages
+})
+
+// Render all pages:
+{data.pages.map((page, i) => (
+  <Fragment key={i}>
+    {page.items.map(item => <div key={item.id}>{item.name}</div>)}
+  </Fragment>
+))}
+
+// Load more:
+<button onClick={() => fetchNextPage()} disabled={!hasNextPage || isFetchingNextPage}>
+  {isFetchingNextPage ? 'Loading...' : hasNextPage ? 'Load More' : 'No more'}
+</button>
+```
+
+**Gotcha:** `data` is `{ pages, pageParams }`, not flat data. `initialData` and `placeholderData` must match this shape.
+
+## Paginated Queries (keep previous data)
+
+```tsx
+import { keepPreviousData, useQuery } from '@tanstack/react-query'
+
+const { data, isPlaceholderData } = useQuery({
+  queryKey: ['projects', page],
+  queryFn: () => fetchProjects(page),
+  placeholderData: keepPreviousData,
+})
+
+// Prefetch next page for instant transitions:
+queryClient.prefetchQuery({
+  queryKey: ['projects', page + 1],
+  queryFn: () => fetchProjects(page + 1),
+})
+```
+
+## Prefetching
+
+```tsx
+// In event handlers (hover/focus):
+const prefetch = () => queryClient.prefetchQuery(todosOptions())
+<button onMouseEnter={prefetch} onFocus={prefetch} onClick={handleClick}>Show</button>
+
+// In components (avoid Suspense waterfalls):
+function Layout({ id }: { id: string }) {
+  usePrefetchQuery(commentsOptions(id)) // starts fetch immediately
+  return (
+    <Suspense fallback="Loading...">
+      <Article id={id} />
+    </Suspense>
+  )
+}
+
+// Prefetch infinite queries:
+queryClient.prefetchInfiniteQuery({
+  ...projectsInfiniteOptions(),
+  pages: 3, // prefetch first 3 pages
+})
+```
+
+## Dependent Queries
+
+```tsx
+const { data: user } = useQuery({
+  queryKey: ['user', email],
+  queryFn: () => getUserByEmail(email),
+})
+
+const { data: projects } = useQuery({
+  queryKey: ['projects', user?.id],
+  queryFn: () => getProjectsByUser(user!.id),
+  enabled: !!user?.id, // waits for user query
+})
+```
+
+**Type-safe disabling with skipToken:**
+
+```tsx
+import { skipToken } from '@tanstack/react-query'
+
+const { data } = useQuery({
+  queryKey: ['projects', userId],
+  queryFn: userId ? () => getProjects(userId) : skipToken,
+})
+```
+
+`skipToken` prevents `refetch()` from working — use `enabled: false` if you need manual refetch.
+
+## setQueryData — immutability
+
+```tsx
+// WRONG — mutating cache in place
+queryClient.setQueryData(['todo', id], (old) => {
+  if (old) old.title = 'new' // DO NOT DO THIS
+  return old
+})
+
+// CORRECT — return new object
+queryClient.setQueryData(['todo', id], (old) =>
+  old ? { ...old, title: 'new' } : old
+)
+```
+
+## Further Reference
+
+- **Full API signatures** (useQuery, useMutation, useInfiniteQuery, QueryClient): See [references/api-reference.md](references/api-reference.md)
+- **SSR & Next.js** (hydration, App Router, streaming): See [references/ssr-nextjs.md](references/ssr-nextjs.md)
+- **Testing** (renderHook, mocking, setup): See [references/testing.md](references/testing.md)
+- **Advanced patterns** (TypeScript, Suspense, waterfalls, network modes): See [references/advanced-patterns.md](references/advanced-patterns.md)