create-xani-agentic-app 1.0.0

package/template/.claude/skills/playwright-cli/references/test-generation.md

@@ -0,0 +1,88 @@
+# Test Generation
+
+Generate Playwright test code automatically as you interact with the browser.
+
+## How It Works
+
+Every action you perform with `playwright-cli` generates corresponding Playwright TypeScript code.
+This code appears in the output and can be copied directly into your test files.
+
+## Example Workflow
+
+```bash
+# Start a session
+playwright-cli open https://example.com/login
+
+# Take a snapshot to see elements
+playwright-cli snapshot
+# Output shows: e1 [textbox "Email"], e2 [textbox "Password"], e3 [button "Sign In"]
+
+# Fill form fields - generates code automatically
+playwright-cli fill e1 "user@example.com"
+# Ran Playwright code:
+# await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
+
+playwright-cli fill e2 "password123"
+# Ran Playwright code:
+# await page.getByRole('textbox', { name: 'Password' }).fill('password123');
+
+playwright-cli click e3
+# Ran Playwright code:
+# await page.getByRole('button', { name: 'Sign In' }).click();
+```
+
+## Building a Test File
+
+Collect the generated code into a Playwright test:
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('login flow', async ({ page }) => {
+  // Generated code from playwright-cli session:
+  await page.goto('https://example.com/login');
+  await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
+  await page.getByRole('textbox', { name: 'Password' }).fill('password123');
+  await page.getByRole('button', { name: 'Sign In' }).click();
+
+  // Add assertions
+  await expect(page).toHaveURL(/.*dashboard/);
+});
+```
+
+## Best Practices
+
+### 1. Use Semantic Locators
+
+The generated code uses role-based locators when possible, which are more resilient:
+
+```typescript
+// Generated (good - semantic)
+await page.getByRole('button', { name: 'Submit' }).click();
+
+// Avoid (fragile - CSS selectors)
+await page.locator('#submit-btn').click();
+```
+
+### 2. Explore Before Recording
+
+Take snapshots to understand the page structure before recording actions:
+
+```bash
+playwright-cli open https://example.com
+playwright-cli snapshot
+# Review the element structure
+playwright-cli click e5
+```
+
+### 3. Add Assertions Manually
+
+Generated code captures actions but not assertions. Add expectations in your test:
+
+```typescript
+// Generated action
+await page.getByRole('button', { name: 'Submit' }).click();
+
+// Manual assertion
+await expect(page.getByText('Success')).toBeVisible();
+```

package/template/.claude/skills/playwright-cli/references/tracing.md

@@ -0,0 +1,139 @@
+# Tracing
+
+Capture detailed execution traces for debugging and analysis. Traces include DOM snapshots, screenshots, network activity, and console logs.
+
+## Basic Usage
+
+```bash
+# Start trace recording
+playwright-cli tracing-start
+
+# Perform actions
+playwright-cli open https://example.com
+playwright-cli click e1
+playwright-cli fill e2 "test"
+
+# Stop trace recording
+playwright-cli tracing-stop
+```
+
+## Trace Output Files
+
+When you start tracing, Playwright creates a `traces/` directory with several files:
+
+### `trace-{timestamp}.trace`
+
+**Action log** - The main trace file containing:
+- Every action performed (clicks, fills, navigations)
+- DOM snapshots before and after each action
+- Screenshots at each step
+- Timing information
+- Console messages
+- Source locations
+
+### `trace-{timestamp}.network`
+
+**Network log** - Complete network activity:
+- All HTTP requests and responses
+- Request headers and bodies
+- Response headers and bodies
+- Timing (DNS, connect, TLS, TTFB, download)
+- Resource sizes
+- Failed requests and errors
+
+### `resources/`
+
+**Resources directory** - Cached resources:
+- Images, fonts, stylesheets, scripts
+- Response bodies for replay
+- Assets needed to reconstruct page state
+
+## What Traces Capture
+
+| Category | Details |
+|----------|---------|
+| **Actions** | Clicks, fills, hovers, keyboard input, navigations |
+| **DOM** | Full DOM snapshot before/after each action |
+| **Screenshots** | Visual state at each step |
+| **Network** | All requests, responses, headers, bodies, timing |
+| **Console** | All console.log, warn, error messages |
+| **Timing** | Precise timing for each operation |
+
+## Use Cases
+
+### Debugging Failed Actions
+
+```bash
+playwright-cli tracing-start
+playwright-cli open https://app.example.com
+
+# This click fails - why?
+playwright-cli click e5
+
+playwright-cli tracing-stop
+# Open trace to see DOM state when click was attempted
+```
+
+### Analyzing Performance
+
+```bash
+playwright-cli tracing-start
+playwright-cli open https://slow-site.com
+playwright-cli tracing-stop
+
+# View network waterfall to identify slow resources
+```
+
+### Capturing Evidence
+
+```bash
+# Record a complete user flow for documentation
+playwright-cli tracing-start
+
+playwright-cli open https://app.example.com/checkout
+playwright-cli fill e1 "4111111111111111"
+playwright-cli fill e2 "12/25"
+playwright-cli fill e3 "123"
+playwright-cli click e4
+
+playwright-cli tracing-stop
+# Trace shows exact sequence of events
+```
+
+## Trace vs Video vs Screenshot
+
+| Feature | Trace | Video | Screenshot |
+|---------|-------|-------|------------|
+| **Format** | .trace file | .webm video | .png/.jpeg image |
+| **DOM inspection** | Yes | No | No |
+| **Network details** | Yes | No | No |
+| **Step-by-step replay** | Yes | Continuous | Single frame |
+| **File size** | Medium | Large | Small |
+| **Best for** | Debugging | Demos | Quick capture |
+
+## Best Practices
+
+### 1. Start Tracing Before the Problem
+
+```bash
+# Trace the entire flow, not just the failing step
+playwright-cli tracing-start
+playwright-cli open https://example.com
+# ... all steps leading to the issue ...
+playwright-cli tracing-stop
+```
+
+### 2. Clean Up Old Traces
+
+Traces can consume significant disk space:
+
+```bash
+# Remove traces older than 7 days
+find .playwright-cli/traces -mtime +7 -delete
+```
+
+## Limitations
+
+- Traces add overhead to automation
+- Large traces can consume significant disk space
+- Some dynamic content may not replay perfectly

package/template/.claude/skills/playwright-cli/references/video-recording.md

@@ -0,0 +1,143 @@
+# Video Recording
+
+Capture browser automation sessions as video for debugging, documentation, or verification. Produces WebM (VP8/VP9 codec).
+
+## Basic Recording
+
+```bash
+# Open browser first
+playwright-cli open
+
+# Start recording
+playwright-cli video-start demo.webm
+
+# Add a chapter marker for section transitions
+playwright-cli video-chapter "Getting Started" --description="Opening the homepage" --duration=2000
+
+# Navigate and perform actions
+playwright-cli goto https://example.com
+playwright-cli snapshot
+playwright-cli click e1
+
+# Add another chapter
+playwright-cli video-chapter "Filling Form" --description="Entering test data" --duration=2000
+playwright-cli fill e2 "test input"
+
+# Stop and save
+playwright-cli video-stop
+```
+
+## Best Practices
+
+### 1. Use Descriptive Filenames
+
+```bash
+# Include context in filename
+playwright-cli video-start recordings/login-flow-2024-01-15.webm
+playwright-cli video-start recordings/checkout-test-run-42.webm
+```
+
+### 2. Record entire hero scripts.
+
+When recording a video for the user or as a proof of work, it is best to create a code snippet and execute it with run-code.
+It allows pulling appropriate pauses between the actions and annotating the video. There are new Playwright APIs for that.
+
+1) Perform scenario using CLI and take note of all locators and actions. You'll need those locators to request thier bounding boxes for highlight.
+2) Create a file with the intended script for video (below). Use pressSequentially w/ delay for nice typing, make reasonable pauses.
+3) Use playwright-cli run-code --file your-script.js
+
+**Important**: Overlays are `pointer-events: none` — they do not interfere with page interactions. You can safely keep sticky overlays visible while clicking, filling, or performing any actions on the page.
+
+```js
+async page => {
+  await page.screencast.start({ path: 'video.webm', size: { width: 1280, height: 800 } });
+  await page.goto('https://demo.playwright.dev/todomvc');
+
+  // Show a chapter card — blurs the page and shows a dialog.
+  // Blocks until duration expires, then auto-removes.
+  // Use this for simple use cases, but always feel free to hand-craft your own beautiful
+  // overlay via await page.screencast.showOverlay().
+  await page.screencast.showChapter('Adding Todo Items', {
+    description: 'We will add several items to the todo list.',
+    duration: 2000,
+  });
+
+  // Perform action
+  await page.getByRole('textbox', { name: 'What needs to be done?' }).pressSequentially('Walk the dog', { delay: 60 });
+  await page.getByRole('textbox', { name: 'What needs to be done?' }).press('Enter');
+  await page.waitForTimeout(1000);
+
+  // Show next chapter
+  await page.screencast.showChapter('Verifying Results', {
+    description: 'Checking the item appeared in the list.',
+    duration: 2000,
+  });
+
+  // Add a sticky annotation that stays while you perform actions.
+  // Overlays are pointer-events: none, so they won't block clicks.
+  const annotation = await page.screencast.showOverlay(`
+    <div style="position: absolute; top: 8px; right: 8px;
+      padding: 6px 12px; background: rgba(0,0,0,0.7);
+      border-radius: 8px; font-size: 13px; color: white;">
+      ✓ Item added successfully
+    </div>
+  `);
+
+  // Perform more actions while the annotation is visible
+  await page.getByRole('textbox', { name: 'What needs to be done?' }).pressSequentially('Buy groceries', { delay: 60 });
+  await page.getByRole('textbox', { name: 'What needs to be done?' }).press('Enter');
+  await page.waitForTimeout(1500);
+
+  // Remove the annotation when done
+  await annotation.dispose();
+
+  // You can also highlight relevant locators and provide contextual annotations.
+  const bounds = await page.getByText('Walk the dog').boundingBox();
+  await page.screencast.showOverlay(`
+    <div style="position: absolute;
+      top: ${bounds.y}px;
+      left: ${bounds.x}px;
+      width: ${bounds.width}px;
+      height: ${bounds.height}px;
+      border: 1px solid red;">
+    </div>
+    <div style="position: absolute;
+      top: ${bounds.y + bounds.height + 5}px;
+      left: ${bounds.x + bounds.width / 2}px;
+      transform: translateX(-50%);
+      padding: 6px;
+      background: #808080;
+      border-radius: 10px;
+      font-size: 14px;
+      color: white;">Check it out, it is right above this text
+    </div>
+  `, { duration: 2000 });
+
+  await page.screencast.stop();
+}
+```
+
+Embrace creativity, overlays are powerful.
+
+### Overlay API Summary
+
+| Method | Use Case |
+|--------|----------|
+| `page.screencast.showChapter(title, { description?, duration?, styleSheet? })` | Full-screen chapter card with blurred backdrop — ideal for section transitions |
+| `page.screencast.showOverlay(html, { duration? })` | Custom HTML overlay — use for callouts, labels, highlights |
+| `disposable.dispose()` | Remove a sticky overlay added without duration |
+| `page.screencast.hideOverlays()` / `page.screencast.showOverlays()` | Temporarily hide/show all overlays |
+
+## Tracing vs Video
+
+| Feature | Video | Tracing |
+|---------|-------|---------|
+| Output | WebM file | Trace file (viewable in Trace Viewer) |
+| Shows | Visual recording | DOM snapshots, network, console, actions |
+| Use case | Demos, documentation | Debugging, analysis |
+| Size | Larger | Smaller |
+
+## Limitations
+
+- Recording adds slight overhead to automation
+- Large recordings can consume significant disk space

package/template/.claude/skills/react-three-fiber/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: react-three-fiber
+description: React Three Fiber 3D renderer for json-render. Use when working with @json-render/react-three-fiber, building 3D scenes from JSON specs, rendering meshes/lights/models/environments, or integrating Three.js with json-render catalogs.
+---
+
+# @json-render/react-three-fiber
+
+React Three Fiber renderer for json-render. 19 built-in 3D components.
+
+## Two Entry Points
+
+| Entry Point | Exports | Use For |
+|-------------|---------|---------|
+| `@json-render/react-three-fiber/catalog` | `threeComponentDefinitions` | Catalog schemas (no R3F dependency, safe for server) |
+| `@json-render/react-three-fiber` | `threeComponents`, `ThreeRenderer`, `ThreeCanvas`, schemas | R3F implementations and renderer |
+
+## Usage Pattern
+
+Pick the 3D components you need from the standard definitions:
+
+```typescript
+import { defineCatalog } from "@json-render/core";
+import { schema } from "@json-render/react/schema";
+import { threeComponentDefinitions } from "@json-render/react-three-fiber/catalog";
+import { defineRegistry } from "@json-render/react";
+import { threeComponents, ThreeCanvas } from "@json-render/react-three-fiber";
+
+// Catalog: pick definitions
+const catalog = defineCatalog(schema, {
+  components: {
+    Box: threeComponentDefinitions.Box,
+    Sphere: threeComponentDefinitions.Sphere,
+    AmbientLight: threeComponentDefinitions.AmbientLight,
+    DirectionalLight: threeComponentDefinitions.DirectionalLight,
+    OrbitControls: threeComponentDefinitions.OrbitControls,
+  },
+  actions: {},
+});
+
+// Registry: pick matching implementations
+const { registry } = defineRegistry(catalog, {
+  components: {
+    Box: threeComponents.Box,
+    Sphere: threeComponents.Sphere,
+    AmbientLight: threeComponents.AmbientLight,
+    DirectionalLight: threeComponents.DirectionalLight,
+    OrbitControls: threeComponents.OrbitControls,
+  },
+});
+```
+
+## Rendering
+
+### ThreeCanvas (convenience wrapper)
+
+```tsx
+<ThreeCanvas
+  spec={spec}
+  registry={registry}
+  shadows
+  camera={{ position: [5, 5, 5], fov: 50 }}
+  style={{ width: "100%", height: "100vh" }}
+/>
+```
+
+### Manual Canvas setup
+
+```tsx
+import { Canvas } from "@react-three/fiber";
+import { ThreeRenderer } from "@json-render/react-three-fiber";
+
+<Canvas shadows>
+  <ThreeRenderer spec={spec} registry={registry}>
+    {/* Additional R3F elements */}
+  </ThreeRenderer>
+</Canvas>
+```
+
+## Available Components (19)
+
+### Primitives (7)
+- `Box` -- width, height, depth, material
+- `Sphere` -- radius, widthSegments, heightSegments, material
+- `Cylinder` -- radiusTop, radiusBottom, height, material
+- `Cone` -- radius, height, material
+- `Torus` -- radius, tube, material
+- `Plane` -- width, height, material
+- `Capsule` -- radius, length, material
+
+All primitives share: `position`, `rotation`, `scale`, `castShadow`, `receiveShadow`, `material`.
+
+### Lights (4)
+- `AmbientLight` -- color, intensity
+- `DirectionalLight` -- position, color, intensity, castShadow
+- `PointLight` -- position, color, intensity, distance, decay
+- `SpotLight` -- position, color, intensity, angle, penumbra
+
+### Other (8)
+- `Group` -- container with position/rotation/scale, supports children
+- `Model` -- GLTF/GLB loader via url prop
+- `Environment` -- HDRI environment map (preset, background, blur, intensity)
+- `Fog` -- linear fog (color, near, far)
+- `GridHelper` -- reference grid (size, divisions, color)
+- `Text3D` -- SDF text (text, fontSize, color, anchorX, anchorY)
+- `PerspectiveCamera` -- camera (position, fov, near, far, makeDefault)
+- `OrbitControls` -- orbit controls (enableDamping, enableZoom, autoRotate)
+
+## Shared Schemas
+
+Reusable Zod schemas for custom 3D catalog definitions:
+
+```typescript
+import { vector3Schema, materialSchema, transformProps, shadowProps } from "@json-render/react-three-fiber";
+import { z } from "zod";
+
+// Custom 3D component
+const myComponentDef = {
+  props: z.object({
+    ...transformProps,
+    ...shadowProps,
+    material: materialSchema.nullable(),
+    myCustomProp: z.string(),
+  }),
+  description: "My custom 3D component",
+};
+```
+
+## Material Schema
+
+```typescript
+materialSchema = z.object({
+  color: z.string().nullable(),         // default "#ffffff"
+  metalness: z.number().nullable(),     // default 0
+  roughness: z.number().nullable(),     // default 1
+  emissive: z.string().nullable(),      // default "#000000"
+  emissiveIntensity: z.number().nullable(), // default 1
+  opacity: z.number().nullable(),       // default 1
+  transparent: z.boolean().nullable(),  // default false
+  wireframe: z.boolean().nullable(),    // default false
+});
+```
+
+## Spec Format
+
+3D specs use the standard json-render flat element format:
+
+```json
+{
+  "root": "scene",
+  "elements": {
+    "scene": {
+      "type": "Group",
+      "props": { "position": [0, 0, 0] },
+      "children": ["light", "box"]
+    },
+    "light": {
+      "type": "AmbientLight",
+      "props": { "intensity": 0.5 },
+      "children": []
+    },
+    "box": {
+      "type": "Box",
+      "props": {
+        "position": [0, 0.5, 0],
+        "material": { "color": "#4488ff", "metalness": 0.3, "roughness": 0.7 }
+      },
+      "children": []
+    }
+  }
+}
+```
+
+## Dependencies
+
+Peer dependencies required:
+- `@react-three/fiber` >= 8.0.0
+- `@react-three/drei` >= 9.0.0
+- `three` >= 0.160.0
+- `react` ^19.0.0
+- `zod` ^4.0.0

package/template/.claude/skills/remotion/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: remotion
+description: |
+  Programmatic video creation with React. Useful for branded explainers, social cuts, dashboards-to-video, and reproducible motion graphics.
+triggers:
+  - "remotion"
+  - "react video"
+  - "programmatic video"
+  - "motion graphics"
+  - "video composition"
+od:
+  mode: video
+  category: video-generation
+  upstream: "https://github.com/remotion-dev/remotion"
+---
+
+# remotion
+
+> Curated from the Remotion team.
+
+## What it does
+
+Programmatic video creation with React. Useful for branded explainers, social cuts, dashboards-to-video, and reproducible motion graphics.
+
+## Source
+
+- Upstream: https://github.com/remotion-dev/remotion
+- Category: `video-generation`
+
+## How to use
+
+This catalogue entry advertises the skill in Open Design so the agent
+discovers it during planning. To run the full upstream workflow with
+its original assets, scripts, and references, install the upstream
+bundle into your active agent's skills directory:
+
+```bash
+# Inspect the upstream README for exact paths
+open https://github.com/remotion-dev/remotion
+```
+
+Then ask the agent to invoke this skill by name (`remotion`) or with
+one of the trigger phrases listed in this skill's frontmatter.

package/template/.claude/skills/review-pr/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: review-pr
+description: >
+  Review pull requests with complexity-adaptive depth — spawning deep-dive agents for medium
+  and complex PRs. Use this skill when the user says "review this PR", "review PR #123",
+  "check this pull request", "give me a code review", or wants feedback on a PR before merging.
+  Also use when the user says "/review-pr" or pastes a GitHub PR URL. Requires the GitHub CLI (gh).
+---
+
+# Review Pull Request
+
+Review pull requests with a depth that matches their complexity. Simple PRs get a direct review; complex PRs get parallel deep-dive agents analyzing security, performance, and architecture.
+
+## Arguments
+
+The user should provide PR number(s) or URL(s). If none provided, ask for them.
+
+## Instructions
+
+### Step 1: Retrieve PR Details
+
+Use the GitHub CLI to get the full picture:
+
+```bash
+gh pr view {pr_number} --json title,body,files,additions,deletions,commits,author,reviews,comments
+gh pr diff {pr_number}
+```
+
+### Step 2: Assess Complexity
+
+Score the PR based on:
+- Number of files changed
+- Lines added/removed
+- Number of commits
+- Whether changes touch core/architectural files
+
+**Simple** (direct review, no agents):
+- 5 or fewer files AND 100 or fewer lines AND single author
+
+**Medium** (1-2 deep-dive agents):
+- 6-15 files, OR 100-500 lines, OR 2 contributors
+
+**Complex** (up to 3 deep-dive agents):
+- More than 15 files, OR more than 500 lines, OR more than 2 contributors, OR touches core architecture
+
+### Step 3: Analyze
+
+**For Simple PRs**: review directly — read the diff, check for issues, provide feedback.
+
+**For Medium/Complex PRs**: spawn deep-dive agents in parallel using the `Agent` tool with `subagent_type: "deep-dive"`. Each agent gets a focused area:
+
+- **Agent 1 — Code Quality**: conventions, patterns, maintainability, test coverage
+- **Agent 2 — Security**: input validation, auth checks, injection risks, data exposure
+- **Agent 3 — Architecture** (Complex only): design patterns, separation of concerns, performance implications, backwards compatibility
+
+Each agent receives the PR diff and description and returns a structured review.
+
+### Step 4: Vision Alignment
+
+Read the project's `README.md` and `CLAUDE.md` to understand the application's purpose. Assess whether the PR aligns with the project's intended direction. Flag significant deviations — not as a blocker, but as a consideration for the reviewer.
+
+### Step 5: Safety Assessment
+
+Provide an overall assessment:
+- **Safe to merge**: no significant issues found
+- **Merge with caution**: minor issues that should be noted but aren't blocking
+- **Needs changes**: issues that should be fixed before merging
+
+Include a risk level (low/medium/high) with justification.
+
+### Step 6: Report
+
+Structure the review as:
+
+```
+## PR Review: #{pr_number} — {title}
+
+### Complexity: {Simple|Medium|Complex}
+{Brief justification}
+
+### Summary
+{2-3 sentence overview of what the PR does}
+
+### Issues Found
+{Grouped by severity: high → medium → low}
+- **{severity}**: {file:line} — {description}
+
+### Improvements Suggested
+{Optional improvements ranked by importance and implementation complexity}
+
+### Vision Alignment
+{Does this PR align with the project's direction?}
+
+### Verdict: {Safe to merge | Merge with caution | Needs changes}
+Risk level: {low|medium|high}
+{Brief justification}
+```