@ivannxbt/ai-config 0.1.0

package/.github/skills/vercel-react-best-practices/rules/server-cache-react.md

@@ -0,0 +1,76 @@
+---
+title: Per-Request Deduplication with React.cache()
+impact: MEDIUM
+impactDescription: deduplicates within request
+tags: server, cache, react-cache, deduplication
+---
+
+## Per-Request Deduplication with React.cache()
+
+Use `React.cache()` for server-side request deduplication. Authentication and database queries benefit most.
+
+**Usage:**
+
+```typescript
+import { cache } from 'react'
+
+export const getCurrentUser = cache(async () => {
+  const session = await auth()
+  if (!session?.user?.id) return null
+  return await db.user.findUnique({
+    where: { id: session.user.id }
+  })
+})
+```
+
+Within a single request, multiple calls to `getCurrentUser()` execute the query only once.
+
+**Avoid inline objects as arguments:**
+
+`React.cache()` uses shallow equality (`Object.is`) to determine cache hits. Inline objects create new references each call, preventing cache hits.
+
+**Incorrect (always cache miss):**
+
+```typescript
+const getUser = cache(async (params: { uid: number }) => {
+  return await db.user.findUnique({ where: { id: params.uid } })
+})
+
+// Each call creates new object, never hits cache
+getUser({ uid: 1 })
+getUser({ uid: 1 })  // Cache miss, runs query again
+```
+
+**Correct (cache hit):**
+
+```typescript
+const getUser = cache(async (uid: number) => {
+  return await db.user.findUnique({ where: { id: uid } })
+})
+
+// Primitive args use value equality
+getUser(1)
+getUser(1)  // Cache hit, returns cached result
+```
+
+If you must pass objects, pass the same reference:
+
+```typescript
+const params = { uid: 1 }
+getUser(params)  // Query runs
+getUser(params)  // Cache hit (same reference)
+```
+
+**Next.js-Specific Note:**
+
+In Next.js, the `fetch` API is automatically extended with request memoization. Requests with the same URL and options are automatically deduplicated within a single request, so you don't need `React.cache()` for `fetch` calls. However, `React.cache()` is still essential for other async tasks:
+
+- Database queries (Prisma, Drizzle, etc.)
+- Heavy computations
+- Authentication checks
+- File system operations
+- Any non-fetch async work
+
+Use `React.cache()` to deduplicate these operations across your component tree.
+
+Reference: [React.cache documentation](https://react.dev/reference/react/cache)

package/.github/skills/vercel-react-best-practices/rules/server-dedup-props.md

@@ -0,0 +1,65 @@
+---
+title: Avoid Duplicate Serialization in RSC Props
+impact: LOW
+impactDescription: reduces network payload by avoiding duplicate serialization
+tags: server, rsc, serialization, props, client-components
+---
+
+## Avoid Duplicate Serialization in RSC Props
+
+**Impact: LOW (reduces network payload by avoiding duplicate serialization)**
+
+RSC→client serialization deduplicates by object reference, not value. Same reference = serialized once; new reference = serialized again. Do transformations (`.toSorted()`, `.filter()`, `.map()`) in client, not server.
+
+**Incorrect (duplicates array):**
+
+```tsx
+// RSC: sends 6 strings (2 arrays × 3 items)
+<ClientList usernames={usernames} usernamesOrdered={usernames.toSorted()} />
+```
+
+**Correct (sends 3 strings):**
+
+```tsx
+// RSC: send once
+<ClientList usernames={usernames} />
+
+// Client: transform there
+'use client'
+const sorted = useMemo(() => [...usernames].sort(), [usernames])
+```
+
+**Nested deduplication behavior:**
+
+Deduplication works recursively. Impact varies by data type:
+
+- `string[]`, `number[]`, `boolean[]`: **HIGH impact** - array + all primitives fully duplicated
+- `object[]`: **LOW impact** - array duplicated, but nested objects deduplicated by reference
+
+```tsx
+// string[] - duplicates everything
+usernames={['a','b']} sorted={usernames.toSorted()} // sends 4 strings
+
+// object[] - duplicates array structure only
+users={[{id:1},{id:2}]} sorted={users.toSorted()} // sends 2 arrays + 2 unique objects (not 4)
+```
+
+**Operations breaking deduplication (create new references):**
+
+- Arrays: `.toSorted()`, `.filter()`, `.map()`, `.slice()`, `[...arr]`
+- Objects: `{...obj}`, `Object.assign()`, `structuredClone()`, `JSON.parse(JSON.stringify())`
+
+**More examples:**
+
+```tsx
+// ❌ Bad
+<C users={users} active={users.filter(u => u.active)} />
+<C product={product} productName={product.name} />
+
+// ✅ Good
+<C users={users} />
+<C product={product} />
+// Do filtering/destructuring in client
+```
+
+**Exception:** Pass derived data when transformation is expensive or client doesn't need original.

package/.github/skills/vercel-react-best-practices/rules/server-parallel-fetching.md

@@ -0,0 +1,83 @@
+---
+title: Parallel Data Fetching with Component Composition
+impact: CRITICAL
+impactDescription: eliminates server-side waterfalls
+tags: server, rsc, parallel-fetching, composition
+---
+
+## Parallel Data Fetching with Component Composition
+
+React Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching.
+
+**Incorrect (Sidebar waits for Page's fetch to complete):**
+
+```tsx
+export default async function Page() {
+  const header = await fetchHeader()
+  return (
+    <div>
+      <div>{header}</div>
+      <Sidebar />
+    </div>
+  )
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+```
+
+**Correct (both fetch simultaneously):**
+
+```tsx
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+export default function Page() {
+  return (
+    <div>
+      <Header />
+      <Sidebar />
+    </div>
+  )
+}
+```
+
+**Alternative with children prop:**
+
+```tsx
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+function Layout({ children }: { children: ReactNode }) {
+  return (
+    <div>
+      <Header />
+      {children}
+    </div>
+  )
+}
+
+export default function Page() {
+  return (
+    <Layout>
+      <Sidebar />
+    </Layout>
+  )
+}
+```

package/.github/skills/vercel-react-best-practices/rules/server-serialization.md

@@ -0,0 +1,38 @@
+---
+title: Minimize Serialization at RSC Boundaries
+impact: HIGH
+impactDescription: reduces data transfer size
+tags: server, rsc, serialization, props
+---
+
+## Minimize Serialization at RSC Boundaries
+
+The React Server/Client boundary serializes all object properties into strings and embeds them in the HTML response and subsequent RSC requests. This serialized data directly impacts page weight and load time, so **size matters a lot**. Only pass fields that the client actually uses.
+
+**Incorrect (serializes all 50 fields):**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()  // 50 fields
+  return <Profile user={user} />
+}
+
+'use client'
+function Profile({ user }: { user: User }) {
+  return <div>{user.name}</div>  // uses 1 field
+}
+```
+
+**Correct (serializes only 1 field):**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()
+  return <Profile name={user.name} />
+}
+
+'use client'
+function Profile({ name }: { name: string }) {
+  return <div>{name}</div>
+}
+```

package/.github/skills/web-design-guidelines/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: web-design-guidelines
+description: Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".
+metadata:
+  author: vercel
+  version: "1.0.0"
+  argument-hint: <file-or-pattern>
+---
+
+# Web Interface Guidelines
+
+Review files for compliance with Web Interface Guidelines.
+
+## How It Works
+
+1. Fetch the latest guidelines from the source URL below
+2. Read the specified files (or prompt user for files/pattern)
+3. Check against all rules in the fetched guidelines
+4. Output findings in the terse `file:line` format
+
+## Guidelines Source
+
+Fetch fresh guidelines before each review:
+
+```
+https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md
+```
+
+Use WebFetch to retrieve the latest rules. The fetched content contains all the rules and output format instructions.
+
+## Usage
+
+When a user provides a file or pattern argument:
+1. Fetch guidelines from the source URL above
+2. Read the specified files
+3. Apply all rules from the fetched guidelines
+4. Output findings using the format specified in the guidelines
+
+If no files specified, ask the user which files to review.

package/.github/workflows/dependency-review.yml

@@ -0,0 +1,25 @@
+# Dependency Review Action
+#
+# This Action scans dependency manifest files changed in pull requests and
+# surfaces known-vulnerable versions before merge.
+name: Dependency review
+
+on:
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  dependency-review:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Dependency Review
+        uses: actions/dependency-review-action@v4
+        with:
+          comment-summary-in-pr: always

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,33 @@
+# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
+# For more information see: https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages
+
+name: Node.js Package
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npm test
+
+  publish-npm:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org/
+      - run: npm ci
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{secrets.npm_token}}

package/.github/workflows/validate.yml

@@ -0,0 +1,48 @@
+name: Validate Configuration Files
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Validate manifest JSON
+        run: node -e "JSON.parse(require('node:fs').readFileSync('configs.manifest.json','utf8'))"
+
+      - name: Verify directory structure from manifest
+        run: |
+          node --input-type=module <<'EOF'
+          import fs from 'node:fs';
+
+          const configs = JSON.parse(fs.readFileSync('configs.manifest.json', 'utf8'));
+          const requiredPaths = [...configs.map((config) => config.key), 'scripts'];
+
+          for (const target of requiredPaths) {
+            if (!fs.existsSync(target) || !fs.statSync(target).isDirectory()) {
+              console.error(`Missing required directory: ${target}`);
+              process.exit(1);
+            }
+            console.log(`OK ${target}`);
+          }
+          EOF
+
+      - name: Run installer tests
+        run: npm test
+
+      - name: Smoke-test installer dry run
+        run: |
+          mkdir -p /tmp/config-installer-smoke
+          node scripts/install.mjs --all --dry-run --yes /tmp/config-installer-smoke

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ivannxbt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,160 @@
+# ai config
+
+> personal configuration files for ai coding assistants. consistent ai behavior across all projects.
+
+---
+
+## installation
+
+```bash
+npx @ivannxbt/ai-config --all --yes
+```
+
+by default this installs the config folders directly into your home directory (`~`).
+
+use `--link` to symlink instead of copy (updates sync automatically):
+
+```bash
+npx @ivannxbt/ai-config --all --link --yes
+```
+
+preview actions without changing files:
+
+```bash
+npx @ivannxbt/ai-config --all --dry-run --yes
+```
+
+install into another destination explicitly if you do not want `~`:
+
+```bash
+npx @ivannxbt/ai-config --all --yes /path/to/your/project
+```
+
+for local development or if you prefer cloning:
+
+```bash
+git clone https://github.com/ivannxbt/config.git
+cd config
+./install.sh /path/to/your/project
+```
+
+requires node.js 20 or newer.
+
+on windows powershell:
+
+```powershell
+.\install.ps1 C:\path\to\your\project
+```
+
+`--link` still renders `.codex` as a local copy because codex config needs machine-local path rendering at install time.
+
+### install paths
+
+| use case | command |
+|----------|---------|
+| full config install in `~` | `npx @ivannxbt/ai-config --all --yes` |
+| full config install in another folder | `npx @ivannxbt/ai-config --all --yes /path/to/project` |
+| one reusable skill | `npx skills add https://github.com/ivannxbt/config --skill frontend-design` |
+| all reusable skills | `npx skills add https://github.com/ivannxbt/config --all` |
+| local repo workflow | `./install.sh /path/to/project` |
+
+### installer flags
+
+- `--all`: install every supported config folder
+- `--link`: create directory links instead of copying
+- `--yes` / `-y`: skip final confirmation
+- `--dry-run`: print actions only, no filesystem changes
+- `--force`: allow non-interactive execution
+- `--no-backup`: disable backup-before-replace behavior
+
+by default, existing destination folders are backed up into `.config-backup-YYYYMMDD-HHMMSS` before replacement.
+
+ci validates the manifest, verifies the required directory structure from that manifest, runs `npm test`, and smoke-tests the installer in dry-run mode.
+
+---
+
+## what's inside
+
+| folder | purpose |
+|--------|---------|
+| `.agent/` | lightweight agent configuration and skill links |
+| `.agents/` | generic ai agent instructions (universal fallback for all tools) |
+| `.claude/` | claude code config — agents, skills, commands, settings |
+| `.cursor/` | cursor editor rules |
+| `.codex/` | openai codex agent configuration |
+| `.gemini/` | google gemini cli configuration |
+| `.github/` | github copilot skills + issue/pr templates |
+
+---
+
+supported top-level config folders are defined in `configs.manifest.json`. add or rename folders there first so the installer, tests, and ci stay in sync.
+
+---
+
+## skills
+
+skills extend ai capabilities with domain-specific knowledge. each tool folder contains its own copy of the skills so they work out of the box with any tool.
+
+for codex, the repo tracks a shared `.codex/config.toml.template` with portable `{{HOME}}` placeholders only. the installer renders it to `.codex/config.toml` using the current user's home directory, while machine-local codex settings stay out of the repo.
+
+skills follow the open [agent skills standard](https://agentskills.io) — supported by claude code, cursor, gemini cli, openai codex, github copilot, and more.
+
+| skill | description |
+|-------|-------------|
+| `agent-browser` | browser automation for web testing, form filling, screenshots, and data extraction |
+| `better-auth-best-practices` | integration guide for better auth, the typescript authentication framework |
+| `design-md` | analyze stitch projects and generate semantic design systems as design.md files |
+| `frontend-design` | create distinctive, production-grade frontend interfaces with high design quality |
+| `remotion-best-practices` | best practices for remotion, the react-based video creation library |
+| `skill-creator` | guide for creating new skills that extend ai capabilities |
+| `supabase-postgres-best-practices` | postgres performance optimization and best practices from supabase |
+| `ui-skills` | opinionated constraints for building better interfaces with tailwind, animations, and accessibility |
+| `vercel-react-best-practices` | react and next.js performance optimization guidelines from vercel |
+| `web-design-guidelines` | review ui code for web interface guidelines compliance and accessibility |
+
+---
+
+## skills.sh
+
+this repo can be consumed directly with [skills.sh](https://skills.sh/):
+
+```bash
+npx skills add https://github.com/ivannxbt/config --all
+```
+
+or install a single skill:
+
+```bash
+npx skills add https://github.com/ivannxbt/config --skill frontend-design
+```
+
+generate commands for every available skill:
+
+```bash
+npm run skills:catalog
+```
+
+notes:
+- keep the repo public so skills.sh users can install from github.
+- installs happen client-side via `npx skills add ...`; there is no separate upload step in this repo.
+- this path installs reusable skills only. it does not install full dotfolder config like `.codex`, `.cursor`, or `.claude`.
+
+## publishing
+
+publish the cli as a public scoped npm package so users can install without cloning:
+
+```bash
+npm publish --access public
+```
+
+verify the published package contents before release:
+
+```bash
+npm run pack:check
+```
+
+---
+
+## license
+
+mit

package/bin/ai-config.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+import { runCli } from '../scripts/install.mjs';
+
+runCli().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`[ERROR] ${message}\n`);
+  process.exit(1);
+});

package/configs.manifest.json

@@ -0,0 +1,30 @@
+[
+  {
+    "key": ".agent",
+    "label": "Agent configuration"
+  },
+  {
+    "key": ".agents",
+    "label": "Generic AI agent instructions"
+  },
+  {
+    "key": ".claude",
+    "label": "Claude AI configuration"
+  },
+  {
+    "key": ".cursor",
+    "label": "Cursor editor rules"
+  },
+  {
+    "key": ".codex",
+    "label": "OpenAI Codex configuration"
+  },
+  {
+    "key": ".gemini",
+    "label": "Google Gemini CLI configuration"
+  },
+  {
+    "key": ".github",
+    "label": "GitHub Copilot + templates"
+  }
+]

package/install.ps1

@@ -0,0 +1,18 @@
+param(
+  [Parameter(ValueFromRemainingArguments = $true)]
+  [string[]]$ArgsList
+)
+
+$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$installer = Join-Path $scriptDir "scripts/install.mjs"
+$nodeBin = if ($env:NODE_BIN) { $env:NODE_BIN } else { "node" }
+
+try {
+  $null = Get-Command $nodeBin -ErrorAction Stop
+} catch {
+  Write-Error "Node.js is required but '$nodeBin' was not found in PATH."
+  exit 1
+}
+
+& $nodeBin $installer @ArgsList
+exit $LASTEXITCODE

package/install.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+NODE_BIN="${NODE_BIN:-node}"
+INSTALLER="$SCRIPT_DIR/scripts/install.mjs"
+
+if ! command -v "$NODE_BIN" >/dev/null 2>&1; then
+  echo "Error: Node.js is required but '$NODE_BIN' was not found in PATH." >&2
+  exit 1
+fi
+
+exec "$NODE_BIN" "$INSTALLER" "$@"