create-xani-agentic-app 1.0.0

package/template/.claude/skills/webgpu-threejs-tsl/templates/webgpu-project.js

@@ -0,0 +1,276 @@
+/**
+ * WebGPU Three.js Project Template
+ *
+ * A complete starter template with:
+ * - WebGPU renderer setup
+ * - TSL material example
+ * - Post-processing ready
+ * - Responsive design
+ * - Animation loop
+ *
+ * Usage:
+ * 1. Copy this file to your project
+ * 2. Install Three.js: npm install three
+ * 3. Replace placeholder content with your scene
+ */
+
+import * as THREE from 'three/webgpu';
+import {
+  // Types
+  float,
+  vec2,
+  vec3,
+  vec4,
+  color,
+  uniform,
+
+  // Geometry
+  positionLocal,
+  positionWorld,
+  normalLocal,
+  normalWorld,
+  uv,
+
+  // Camera
+  cameraPosition,
+
+  // Time
+  time,
+  deltaTime,
+
+  // Math
+  mix,
+  smoothstep,
+  clamp,
+  sin,
+  cos,
+
+  // Texture
+  texture,
+
+  // Functions
+  Fn,
+  If,
+  Loop,
+
+  // Post-processing
+  pass
+} from 'three/tsl';
+
+import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
+
+// ============================================
+// CONFIGURATION
+// ============================================
+
+const CONFIG = {
+  // Renderer
+  antialias: true,
+  pixelRatio: Math.min(window.devicePixelRatio, 2),
+
+  // Camera
+  fov: 60,
+  near: 0.1,
+  far: 1000,
+  position: new THREE.Vector3(0, 2, 5),
+
+  // Scene
+  backgroundColor: 0x111111,
+
+  // Controls
+  enableDamping: true,
+  dampingFactor: 0.05
+};
+
+// ============================================
+// GLOBALS
+// ============================================
+
+let camera, scene, renderer, controls;
+let clock;
+
+// Add your uniforms here
+const uniforms = {
+  // Example: myColor: uniform(new THREE.Color(0xff0000))
+};
+
+// ============================================
+// INITIALIZATION
+// ============================================
+
+async function init() {
+  // Clock
+  clock = new THREE.Clock();
+
+  // Scene
+  scene = new THREE.Scene();
+  scene.background = new THREE.Color(CONFIG.backgroundColor);
+
+  // Camera
+  camera = new THREE.PerspectiveCamera(
+    CONFIG.fov,
+    window.innerWidth / window.innerHeight,
+    CONFIG.near,
+    CONFIG.far
+  );
+  camera.position.copy(CONFIG.position);
+
+  // Renderer
+  renderer = new THREE.WebGPURenderer({ antialias: CONFIG.antialias });
+  renderer.setSize(window.innerWidth, window.innerHeight);
+  renderer.setPixelRatio(CONFIG.pixelRatio);
+  document.body.appendChild(renderer.domElement);
+
+  // Initialize WebGPU
+  await renderer.init();
+
+  // Controls
+  controls = new OrbitControls(camera, renderer.domElement);
+  controls.enableDamping = CONFIG.enableDamping;
+  controls.dampingFactor = CONFIG.dampingFactor;
+
+  // Setup scene content
+  setupLights();
+  setupScene();
+
+  // Optional: Setup post-processing
+  // setupPostProcessing();
+
+  // Events
+  window.addEventListener('resize', onWindowResize);
+
+  // Start animation loop
+  renderer.setAnimationLoop(animate);
+}
+
+// ============================================
+// SCENE SETUP
+// ============================================
+
+function setupLights() {
+  // Ambient light
+  const ambientLight = new THREE.AmbientLight(0x404040, 0.5);
+  scene.add(ambientLight);
+
+  // Directional light
+  const directionalLight = new THREE.DirectionalLight(0xffffff, 1);
+  directionalLight.position.set(5, 10, 5);
+  directionalLight.castShadow = true;
+  scene.add(directionalLight);
+
+  // Add more lights as needed
+}
+
+function setupScene() {
+  // ========================================
+  // ADD YOUR SCENE CONTENT HERE
+  // ========================================
+
+  // Example: Create a mesh with TSL material
+  const geometry = new THREE.BoxGeometry(1, 1, 1);
+  const material = createExampleMaterial();
+  const mesh = new THREE.Mesh(geometry, material);
+  scene.add(mesh);
+
+  // Example: Add a floor
+  const floorGeometry = new THREE.PlaneGeometry(10, 10);
+  const floorMaterial = new THREE.MeshStandardNodeMaterial({
+    color: 0x333333
+  });
+  const floor = new THREE.Mesh(floorGeometry, floorMaterial);
+  floor.rotation.x = -Math.PI / 2;
+  floor.position.y = -0.5;
+  scene.add(floor);
+}
+
+function createExampleMaterial() {
+  const material = new THREE.MeshStandardNodeMaterial();
+
+  // ========================================
+  // CUSTOMIZE YOUR MATERIAL HERE
+  // ========================================
+
+  // Example: Animated color
+  material.colorNode = Fn(() => {
+    const t = time.mul(0.5).sin().mul(0.5).add(0.5);
+    return mix(color(0x0066ff), color(0xff6600), t);
+  })();
+
+  // Example: PBR properties
+  material.roughnessNode = float(0.5);
+  material.metalnessNode = float(0.0);
+
+  // Example: Simple fresnel rim
+  material.emissiveNode = Fn(() => {
+    const viewDir = cameraPosition.sub(positionWorld).normalize();
+    const fresnel = float(1.0).sub(normalWorld.dot(viewDir).saturate()).pow(3.0);
+    return color(0x00ffff).mul(fresnel).mul(0.5);
+  })();
+
+  return material;
+}
+
+// ============================================
+// POST-PROCESSING (Optional)
+// ============================================
+
+let postProcessing;
+
+function setupPostProcessing() {
+  // Uncomment and customize as needed
+
+  // postProcessing = new THREE.RenderPipeline(renderer);
+  // const scenePass = pass(scene, camera);
+  // const sceneColor = scenePass.getTextureNode('output');
+  //
+  // // Add effects here
+  // postProcessing.outputNode = sceneColor;
+}
+
+// ============================================
+// ANIMATION LOOP
+// ============================================
+
+function animate() {
+  const delta = clock.getDelta();
+  const elapsed = clock.getElapsedTime();
+
+  // ========================================
+  // UPDATE YOUR SCENE HERE
+  // ========================================
+
+  // Example: Rotate mesh
+  const mesh = scene.children.find((child) => child.type === 'Mesh');
+  if (mesh) {
+    mesh.rotation.y += delta * 0.5;
+  }
+
+  // Update controls
+  controls.update();
+
+  // Render
+  if (postProcessing) {
+    postProcessing.render();
+  } else {
+    renderer.render(scene, camera);
+  }
+}
+
+// ============================================
+// EVENT HANDLERS
+// ============================================
+
+function onWindowResize() {
+  camera.aspect = window.innerWidth / window.innerHeight;
+  camera.updateProjectionMatrix();
+  renderer.setSize(window.innerWidth, window.innerHeight);
+}
+
+// ============================================
+// START
+// ============================================
+
+init().catch(console.error);
+
+// Export for external access if needed
+export { scene, camera, renderer, uniforms };

package/template/.claude/skills/zoom-out/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: zoom-out
+description: Tell the agent to zoom out and give broader context or a higher-level perspective. Use when you're unfamiliar with a section of code or need to understand how it fits into the bigger picture.
+disable-model-invocation: true
+---
+
+I don't know this area of code well. Go up a layer of abstraction. Give me a map of all the relevant modules and callers, using the project's domain glossary vocabulary.

package/template/.mcp.json

@@ -0,0 +1,5 @@
+{
+  "mcpServers": {
+    
+  }
+}

package/template/.nvmrc

@@ -0,0 +1 @@
+20

package/template/.prettierignore

@@ -0,0 +1,25 @@
+# Dependencies
+node_modules/
+pnpm-lock.yaml
+
+# Build outputs
+.next/
+dist/
+build/
+
+# Database
+drizzle/
+
+# Generated files
+*.min.js
+*.min.css
+
+# Template (has its own formatting)
+create-xani-agentic-app/
+
+# Cache
+.cache/
+
+# IDE
+.idea/
+.vscode/

package/template/.prettierrc

@@ -0,0 +1,11 @@
+{
+  "semi": true,
+  "singleQuote": false,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "printWidth": 100,
+  "bracketSpacing": true,
+  "arrowParens": "always",
+  "endOfLine": "lf",
+  "plugins": ["prettier-plugin-tailwindcss"]
+}

package/template/.vscode/settings.json

@@ -0,0 +1 @@
+{}

package/template/.vscode/tasks.json.example

@@ -0,0 +1,85 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "Claude",
+      "type": "shell",
+      "command": "claude --dangerously-skip-permissions",
+      "isBackground": true,
+      "options": {
+        "shell": {
+          "executable": "powershell.exe",
+          "args": ["-NoProfile", "-Command"]
+        }
+      },
+      "presentation": {
+        "reveal": "always",
+        "panel": "dedicated"
+      },
+      "runOptions": {
+        "runOn": "folderOpen"
+      },
+      "problemMatcher": []
+    },
+    {
+      "label": "Drizzle",
+      "type": "shell",
+      "command": "$c = docker ps -q --filter 'publish=5432'; if ($c) { docker stop $c }; docker compose up -d; pnpm run db:studio",
+      "isBackground": true,
+      "options": {
+        "shell": {
+          "executable": "powershell.exe",
+          "args": ["-NoProfile", "-Command"]
+        }
+      },
+      "presentation": {
+        "reveal": "always",
+        "panel": "dedicated"
+      },
+      "runOptions": {
+        "runOn": "folderOpen"
+      },
+      "problemMatcher": []
+    },
+    {
+      "label": "Inngest",
+      "type": "shell",
+      "command": "pnpm dlx inngest-cli@latest dev",
+      "isBackground": true,
+      "options": {
+        "shell": {
+          "executable": "powershell.exe",
+          "args": ["-NoProfile", "-Command"]
+        }
+      },
+      "presentation": {
+        "reveal": "always",
+        "panel": "dedicated"
+      },
+      "runOptions": {
+        "runOn": "folderOpen"
+      },
+      "problemMatcher": []
+    },
+    {
+      "label": "Dev Server",
+      "type": "shell",
+      "command": "pnpm run dev",
+      "isBackground": true,
+      "options": {
+        "shell": {
+          "executable": "powershell.exe",
+          "args": ["-NoProfile", "-Command"]
+        }
+      },
+      "presentation": {
+        "reveal": "always",
+        "panel": "dedicated"
+      },
+      "runOptions": {
+        "runOn": "folderOpen"
+      },
+      "problemMatcher": []
+    }
+  ]
+}

package/template/AGENTS.md

@@ -0,0 +1,37 @@
+# CRITICAL RULES - MUST FOLLOW
+
+## RESPONSES
+
+- Keep responses concise and to the point - unless the user asks otherwise
+
+## PLANNING MODE
+
+- Always ask clarifying questions
+- Never assume design, tech stack or features
+- Use deep-dive sub-agents to assist with research
+- Use deep-dive sub-agents to review the different aspects of your plan before presenting to the user
+
+## CHANGE / EDIT MODE
+
+- Never implement features yourself when possible - use sub-agents!
+- Identify changes from the plan that can be implemented in parallel, and use sub-agents to implement the features efficiently
+- When using sub-agents to implement features, act as a coordinator only
+- Use the best model for the task - premium models for complex tasks (like coding) and mid-tier models for simpler tasks, like documentation
+- After completing features (large or small), always run commands like lint, type check and next build to check code quality
+
+## DATABASE SCHEMA CHANGES
+
+- Whenever you make changes to the database schema, ALWAYS run the drizzle generate and migrate commands
+- NEVER run drizzle push!
+- For all ID columns NOT related to BetterAuth, use UUID for the ID columns and be randomly generated
+
+## TESTING
+
+- Use any testing tools, libraries available to the project for testing your changes
+- Never assume your changes simply work, always test!
+- If the project does not have any testing tools, scripts, MCP tools, skills, etc. available for testing, ask the user whether testing should be skipped.
+
+## UI DESIGN
+
+- Always follow the UI design system when creating or reviewing components or pages.
+- Design System: @DESIGN.md

package/template/CLAUDE.md

@@ -0,0 +1,75 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+@AGENTS.md
+
+## Commands
+
+Package manager is **pnpm** (Node 20, see `.nvmrc`).
+
+| Task | Command |
+|---|---|
+| Dev server (Turbopack) | `pnpm dev` |
+| Production build (runs migrations first) | `pnpm build` |
+| CI build (no migrations) | `pnpm build:ci` |
+| Lint | `pnpm lint` |
+| Type check | `pnpm typecheck` |
+| Lint + typecheck together | `pnpm check` |
+| Format | `pnpm format` / `pnpm format:check` |
+| Generate migration from schema | `pnpm db:generate` |
+| Apply migrations | `pnpm db:migrate` |
+| Drizzle Studio | `pnpm db:studio` |
+
+There is **no test runner** configured. Per `AGENTS.md`, if a change needs testing and no tooling exists, ask the user whether to skip testing. Playwright MCP tools are available for browser-based verification.
+
+After completing features, run `pnpm check` and `pnpm build:ci` to verify code quality.
+
+### Database workflow (critical)
+
+`pnpm build` runs `db:migrate` before `next build`. Migrations live in `drizzle/`. Per `AGENTS.md`: on any schema change, run `db:generate` then `db:migrate` — **never** `db:push` (the `db:push`/`db:dev`/`db:reset` scripts exist but must not be used). All non-BetterAuth ID columns must be randomly-generated UUIDs.
+
+### Local setup
+
+`cp env.example .env` → `docker compose up -d` (Postgres via `pgvector/pgvector:pg18` on port 5432) → `pnpm db:migrate` → `pnpm dev`. `pnpm setup` runs the guided `scripts/setup.ts`.
+
+## Architecture
+
+Next.js 16 App Router + React 19 + TypeScript, Tailwind v4, Better Auth, Drizzle ORM (postgres-js), AI SDK via OpenRouter. Path alias `@/*` → `src/*`.
+
+### Auth (Better Auth)
+
+- `src/lib/auth.ts` — server config. Email/password enabled by default; **no OAuth, no email provider**. Password-reset and email-verification URLs are logged to the terminal in dev (search the dev server output for them). Adding Google OAuth or a real email service is a deliberate follow-up task.
+- `src/lib/auth-client.ts` — React client hooks (`useSession`, `signIn`, `signUp`, etc.).
+- `src/app/api/auth/[...all]/route.ts` — catch-all handler via `toNextJsHandler`.
+- `src/lib/schema.ts` — the four Better Auth tables (`user`, `session`, `account`, `verification`) use `text` IDs (Better Auth requirement). Any new app tables must use UUIDs instead.
+
+### Route protection (two layers)
+
+1. `src/proxy.ts` — Next.js 16 proxy doing **optimistic** cookie-existence redirects for `/dashboard`, `/chat`, `/profile`. Does not validate the session.
+2. `src/lib/session.ts` — `requireAuth()` does real session validation in Server Components and redirects to `/` if unauthenticated. `protectedRoutes` here must stay in sync with the proxy `matcher` and `next.config` is unaware of them.
+
+Protected pages call `requireAuth()`; the proxy is just a fast first gate.
+
+### AI chat
+
+`src/app/api/chat/route.ts` — authenticated POST endpoint. Validates the request with Zod (max 100 messages, 10k chars/part), then `streamText` through OpenRouter (`OPENROUTER_MODEL`, default `openai/gpt-5-mini`) returning a UI message stream. The `/chat` page uses `@ai-sdk/react`.
+
+### Storage abstraction
+
+`src/lib/storage.ts` — single `upload`/`deleteFile` API that switches on `BLOB_READ_WRITE_TOKEN`: Vercel Blob when set, otherwise local `public/uploads/`. Includes filename sanitization, size limits (5MB default), and extension allow-listing.
+
+### Env validation
+
+`src/lib/env.ts` — Zod schemas for server/client env plus `checkEnv()` for runtime warnings. `src/app/api/diagnostics/route.ts` is an intentionally public endpoint returning boolean config flags (no secrets) consumed by the homepage setup checklist.
+
+## Conventions
+
+- UI must follow `DESIGN.md` (shadcn/ui new-york, neutral base, oklch tokens, Tailwind v4 CSS-first config in `globals.css` — no `tailwind.config.ts`). Components in `src/components/ui/`.
+- `AGENTS.md` mandates a plan→split→sub-agent→verify workflow: ask clarifying questions in planning, delegate implementation to sub-agents in parallel where useful, and act as coordinator.
+
+## Docs & specs
+
+- `docs/technical/` — reference notes (AI streaming/structured-data, Better Auth + Polar, react-markdown).
+- `specs/{feature}/` — spec-driven workflow output (requirements, waved task files). Use the `create-spec` / `implement-feature` skills for large multi-session features.
+- `create-xani-agentic-app/` — the CLI scaffolder that publishes this repo as a template; `pnpm sync-template` syncs template files.

package/template/CONTEXT.md

@@ -0,0 +1,29 @@
+# Xani Agentic Starter Kit
+
+A production-oriented starter kit for building AI-powered web apps with an agentic development workflow. This document is the canonical glossary for the project — especially its three easily-confused names.
+
+## Language
+
+**Xani Agentic Starter Kit**:
+The human-readable brand / display name of the project, shown in the README title, site footer, setup script, and skill description.
+_Avoid_: Agentic Coding Starter Kit, Xani Agentic App.
+
+**xani-agentic-starter-kit**:
+The repository and the root `package.json` name — i.e. the kit itself (the Next.js app, schema, skills, docs). GitHub slug: `AlexandreXavier/xani-agentic-starter-kit`.
+_Avoid_: agentic-coding-starter-kit.
+
+**create-xani-agentic-app**:
+The npm package and `npx` command that scaffolds a new copy of the kit (`npx create-xani-agentic-app my-app`). Lives in the repo folder of the same name and follows npm's `create-*` convention (package name == bin name). Distinct from the kit it publishes.
+_Avoid_: create-agentic-app, create-app, create-xani-app.
+
+## Relationships
+
+- The **create-xani-agentic-app** CLI scaffolds an instance of the **xani-agentic-starter-kit**.
+- Both live in the **xani-agentic-starter-kit** repo (`AlexandreXavier/xani-agentic-starter-kit`); the CLI is published from the `create-xani-agentic-app/` subfolder.
+- **Xani Agentic Starter Kit** is the display name of the **xani-agentic-starter-kit**; it is never the name of the CLI.
+- The skill installs with `npx skills add AlexandreXavier/xani-agentic-starter-kit@create-xani-agentic-app` — slug is the kit, the suffix is the CLI.
+
+## Flagged ambiguities
+
+- "create-app" was proposed as the command name — rejected: too generic, unpublishable on npm, and loses the "xani" identity. Canonical command is **create-xani-agentic-app**.
+- The repo name (the kit) and the npm package name (the CLI) are deliberately different. They are not interchangeable.