create-xani-agentic-app 1.0.0

package/template/.agents/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/.agents/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/.agents/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/.agents/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}
+```

package/template/.agents/skills/security-scanner/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: security-scanner
+description: >-
+  Performs comprehensive OWASP Top 10:2025 security vulnerability analysis on any codebase.
+  Use this skill whenever the user asks to: review code for security, perform a security audit,
+  scan for vulnerabilities, find security issues, improve application security, check for OWASP
+  compliance, do a penetration test review, assess security posture, look for security flaws,
+  scan for security risks, harden an application, or check code for exploits. Also trigger when
+  the user mentions OWASP, CVEs, CWEs, security hardening, vulnerability assessment, or asks
+  for a security report — even if they don't explicitly say "security scan." This skill works
+  on any codebase in any language (JavaScript, TypeScript, Python, Java, Go, Ruby, C#, PHP, etc.).
+---
+
+# Security Scanner — OWASP Top 10:2025
+
+Performs a systematic security audit of any codebase against all 10 OWASP 2025 categories. Produces a structured markdown report with severity ratings, code locations, and actionable remediation guidance.
+
+## Execution Flow
+
+Follow these four steps in order. Do not skip any step.
+
+### Step 1: Detect Project Context
+
+Determine whether you are working within an existing project or a blank workspace.
+
+Check for source code by looking for common project indicators:
+- `package.json`, `requirements.txt`, `go.mod`, `pom.xml`, `Cargo.toml`, `Gemfile`, `*.csproj`, `composer.json`
+- Or any `src/`, `app/`, `lib/` directory containing code files
+
+**If source code is found:** Use the current working directory as the analysis target. Proceed to Step 2.
+
+**If NO source code is found:** Ask the user for a GitHub repository URL. Then clone it:
+```bash
+gh repo clone <url> ./audit-target
+```
+Use `./audit-target` as the analysis target directory. Proceed to Step 2.
+
+### Step 2: Reconnaissance
+
+Before scanning for vulnerabilities, understand what you're analyzing. This context shapes which patterns matter most.
+
+1. **Identify the tech stack** — Read the main dependency manifest (package.json, requirements.txt, etc.) to determine language(s), framework(s), and key libraries
+2. **Map the project structure** — Use Glob to find all source files and understand the directory layout
+3. **Locate entry points** — Find API routes, controllers, handlers, page components (e.g., `**/api/**/*.ts`, `**/routes/**`, `**/controllers/**`, `**/views/**`)
+4. **Find config files** — Glob for `**/*.config.*`, `**/.env*`, `**/settings.*`, `**/application.*`
+5. **Identify auth modules** — Search for authentication/authorization logic, session management, middleware
+6. **Find database access** — Locate ORM models, raw query files, database connection setup
+
+Record your findings — they guide which detection patterns to prioritize in Step 3.
+
+### Step 3: Systematic Analysis
+
+For each OWASP category A01 through A10:
+
+1. **Read the reference file** for that category from `references/` to load the relevant CWEs, detection patterns, and grep expressions
+2. **Search the codebase** using the patterns from the reference file — use Grep for pattern matching and Glob for file discovery
+3. **Read flagged files** to confirm findings and get exact line numbers
+4. **Record each finding** with: file path, line number(s), severity level, CWE, description, evidence (code snippet), and recommended fix
+
+Analyze each category in order:
+
+#### A01: Broken Access Control
+See [references/A01-broken-access-control.md](references/A01-broken-access-control.md) for CWEs, detection patterns, and fix examples.
+
+Focus on: missing auth middleware on routes, IDOR (user-controlled IDs without ownership checks), permissive CORS, directory traversal, missing CSRF protection, privilege escalation, force browsing to admin/debug endpoints.
+
+#### A02: Security Misconfiguration
+See [references/A02-security-misconfiguration.md](references/A02-security-misconfiguration.md).
+
+Focus on: debug mode in production, default credentials, verbose error messages exposing internals, unnecessary features enabled, missing security headers, hardcoded secrets, exposed environment variables.
+
+#### A03: Software Supply Chain Failures
+See [references/A03-software-supply-chain-failures.md](references/A03-software-supply-chain-failures.md).
+
+Focus on: known vulnerable dependency versions, unpinned dependencies, CDN scripts without SRI, missing lock files, dependencies from untrusted sources.
+
+#### A04: Cryptographic Failures
+See [references/A04-cryptographic-failures.md](references/A04-cryptographic-failures.md).
+
+Focus on: weak password hashing (MD5, SHA1), missing salt, hardcoded keys/secrets, weak randomness (Math.random for tokens), cookies missing Secure flag, sensitive data in logs, base64 used as "encryption."
+
+#### A05: Injection
+See [references/A05-injection.md](references/A05-injection.md).
+
+Focus on: SQL injection (string concatenation in queries), command injection (exec/spawn with user input), XSS (dangerouslySetInnerHTML, innerHTML), eval() with user input, SSRF (fetching user-supplied URLs), template injection.
+
+#### A06: Insecure Design
+See [references/A06-insecure-design.md](references/A06-insecure-design.md).
+
+Focus on: missing rate limiting on auth endpoints, no input validation, no password complexity requirements, missing account lockout, unrestricted file uploads, guessable/non-expiring tokens.
+
+#### A07: Authentication Failures
+See [references/A07-authentication-failures.md](references/A07-authentication-failures.md).
+
+Focus on: weak/predictable session tokens, sessions that never expire, credentials in logs/URLs, user enumeration via different error messages, reset tokens in API responses, cookies without HttpOnly/Secure/SameSite, hard-coded credentials.
+
+#### A08: Software or Data Integrity Failures
+See [references/A08-software-data-integrity-failures.md](references/A08-software-data-integrity-failures.md).
+
+Focus on: eval()/Function() with user input, deserialization of untrusted data, CDN scripts without integrity hashes, mass assignment/prototype pollution, auto-updates without signature verification.
+
+#### A09: Security Logging and Alerting Failures
+See [references/A09-security-logging-alerting-failures.md](references/A09-security-logging-alerting-failures.md).
+
+Focus on: passwords/tokens/PII in logs, missing audit logging for auth events, no logging on access control failures, error details exposed to users, console.log-only logging without persistence.
+
+#### A10: Mishandling of Exceptional Conditions
+See [references/A10-mishandling-exceptional-conditions.md](references/A10-mishandling-exceptional-conditions.md).
+
+Focus on: empty catch blocks, stack traces returned to users, fail-open patterns, missing error handling on async operations, resource leaks on exceptions, missing transaction rollbacks.
+
+### Step 4: Generate Report
+
+1. Get today's date and create the output directory:
+   ```bash
+   mkdir -p ./audit/YYYY-MM-DD/
+   ```
+
+2. Read the report template from [references/report-template.md](references/report-template.md)
+
+3. Fill in the template with all findings from Step 3 and write the completed report to:
+   ```
+   ./audit/YYYY-MM-DD/security-report.md
+   ```
+
+4. Present a brief summary to the user: total findings by severity, overall risk score, and the top 3 most critical items to address immediately.
+
+## Severity Classification
+
+Assign each finding one of these severity levels:
+
+- **Critical** (10 pts): Actively exploitable with immediate data breach risk. Examples: SQL injection, remote code execution, authentication bypass, exposed credentials, command injection.
+
+- **High** (7 pts): Exploitable with moderate effort, significant impact. Examples: XSS, CSRF, weak cryptography, IDOR, SSRF, known vulnerable dependencies.
+
+- **Medium** (4 pts): Requires specific conditions or must be chained with other vulnerabilities. Examples: missing security headers, verbose errors, user enumeration, missing rate limiting.
+
+- **Low** (2 pts): Defense-in-depth issues, best-practice deviations. Examples: weak password policy, console-only logging, missing SRI on CDN scripts.
+
+- **Info** (0 pts): Observations and recommendations with no direct exploit path. Examples: outdated but non-vulnerable dependencies, missing SBOM, code quality notes.
+
+## Risk Score
+
+Sum all finding points to calculate the overall risk score:
+- **0–10**: Low Risk
+- **11–30**: Moderate Risk
+- **31–60**: High Risk
+- **61+**: Critical Risk
+
+## Important Guidelines
+
+- **Read-only analysis**: Never modify any source files in the target project. The audit directory is the only location where files should be written.
+- **Cover all 10 categories**: If a category has no findings, still include it in the report with "No issues identified" and note what was checked.
+- **Be specific**: Every finding must reference a specific file path and line number(s). Include the actual vulnerable code snippet as evidence.
+- **Provide fixes**: Every finding must include an actionable remediation recommendation with a code example showing the fix.
+- **No false positives**: Read and understand the code context before flagging. A `console.log` in a build script is not the same as a `console.log` leaking passwords in a login handler.
+- **Prioritize**: Order the remediation priority section by actual exploitability and impact, not just severity label.