create-xani-agentic-app 1.0.0

package/template/.agents/skills/better-auth-best-practices/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: better-auth-best-practices
+description: Configure Better Auth server and client, set up database adapters, manage sessions, add plugins, and handle environment variables. Use when users mention Better Auth, betterauth, auth.ts, or need to set up TypeScript authentication with email/password, OAuth, or plugin configuration.
+---
+
+# Better Auth Integration Guide
+
+**Always consult [better-auth.com/docs](https://better-auth.com/docs) for code examples and latest API.**
+
+---
+
+## Setup Workflow
+
+1. Install: `npm install better-auth`
+2. Set env vars: `BETTER_AUTH_SECRET` and `BETTER_AUTH_URL`
+3. Create `auth.ts` with database + config
+4. Create route handler for your framework
+5. Run `npx @better-auth/cli@latest migrate`
+6. Verify: call `GET /api/auth/ok` — should return `{ status: "ok" }`
+
+---
+
+## Quick Reference
+
+### Environment Variables
+- `BETTER_AUTH_SECRET` - Encryption secret (min 32 chars). Generate: `openssl rand -base64 32`
+- `BETTER_AUTH_URL` - Base URL (e.g., `https://example.com`)
+
+Only define `baseURL`/`secret` in config if env vars are NOT set.
+
+### File Location
+CLI looks for `auth.ts` in: `./`, `./lib`, `./utils`, or under `./src`. Use `--config` for custom path.
+
+### CLI Commands
+- `npx @better-auth/cli@latest migrate` - Apply schema (built-in adapter)
+- `npx @better-auth/cli@latest generate` - Generate schema for Prisma/Drizzle
+- `npx @better-auth/cli mcp --cursor` - Add MCP to AI tools
+
+**Re-run after adding/changing plugins.**
+
+---
+
+## Core Config Options
+
+| Option | Notes |
+|--------|-------|
+| `appName` | Optional display name |
+| `baseURL` | Only if `BETTER_AUTH_URL` not set |
+| `basePath` | Default `/api/auth`. Set `/` for root. |
+| `secret` | Only if `BETTER_AUTH_SECRET` not set |
+| `database` | Required for most features. See adapters docs. |
+| `secondaryStorage` | Redis/KV for sessions & rate limits |
+| `emailAndPassword` | `{ enabled: true }` to activate |
+| `socialProviders` | `{ google: { clientId, clientSecret }, ... }` |
+| `plugins` | Array of plugins |
+| `trustedOrigins` | CSRF whitelist |
+
+---
+
+## Database
+
+**Direct connections:** Pass `pg.Pool`, `mysql2` pool, `better-sqlite3`, or `bun:sqlite` instance.
+
+**ORM adapters:** Import from `better-auth/adapters/drizzle`, `better-auth/adapters/prisma`, `better-auth/adapters/mongodb`.
+
+**Critical:** Better Auth uses adapter model names, NOT underlying table names. If Prisma model is `User` mapping to table `users`, use `modelName: "user"` (Prisma reference), not `"users"`.
+
+---
+
+## Session Management
+
+**Storage priority:**
+1. If `secondaryStorage` defined → sessions go there (not DB)
+2. Set `session.storeSessionInDatabase: true` to also persist to DB
+3. No database + `cookieCache` → fully stateless mode
+
+**Cookie cache strategies:**
+- `compact` (default) - Base64url + HMAC. Smallest.
+- `jwt` - Standard JWT. Readable but signed.
+- `jwe` - Encrypted. Maximum security.
+
+**Key options:** `session.expiresIn` (default 7 days), `session.updateAge` (refresh interval), `session.cookieCache.maxAge`, `session.cookieCache.version` (change to invalidate all sessions).
+
+---
+
+## User & Account Config
+
+**User:** `user.modelName`, `user.fields` (column mapping), `user.additionalFields`, `user.changeEmail.enabled` (disabled by default), `user.deleteUser.enabled` (disabled by default).
+
+**Account:** `account.modelName`, `account.accountLinking.enabled`, `account.storeAccountCookie` (for stateless OAuth).
+
+**Required for registration:** `email` and `name` fields.
+
+---
+
+## Email Flows
+
+- `emailVerification.sendVerificationEmail` - Must be defined for verification to work
+- `emailVerification.sendOnSignUp` / `sendOnSignIn` - Auto-send triggers
+- `emailAndPassword.sendResetPassword` - Password reset email handler
+
+---
+
+## Security
+
+**In `advanced`:**
+- `useSecureCookies` - Force HTTPS cookies
+- `disableCSRFCheck` - ⚠️ Security risk
+- `disableOriginCheck` - ⚠️ Security risk  
+- `crossSubDomainCookies.enabled` - Share cookies across subdomains
+- `ipAddress.ipAddressHeaders` - Custom IP headers for proxies
+- `database.generateId` - Custom ID generation or `"serial"`/`"uuid"`/`false`
+
+**Rate limiting:** `rateLimit.enabled`, `rateLimit.window`, `rateLimit.max`, `rateLimit.storage` ("memory" | "database" | "secondary-storage").
+
+---
+
+## Hooks
+
+**Endpoint hooks:** `hooks.before` / `hooks.after` - Array of `{ matcher, handler }`. Use `createAuthMiddleware`. Access `ctx.path`, `ctx.context.returned` (after), `ctx.context.session`.
+
+**Database hooks:** `databaseHooks.user.create.before/after`, same for `session`, `account`. Useful for adding default values or post-creation actions.
+
+**Hook context (`ctx.context`):** `session`, `secret`, `authCookies`, `password.hash()`/`verify()`, `adapter`, `internalAdapter`, `generateId()`, `tables`, `baseURL`.
+
+---
+
+## Plugins
+
+**Import from dedicated paths for tree-shaking:**
+```
+import { twoFactor } from "better-auth/plugins/two-factor"
+```
+NOT `from "better-auth/plugins"`.
+
+**Popular plugins:** `twoFactor`, `organization`, `passkey`, `magicLink`, `emailOtp`, `username`, `phoneNumber`, `admin`, `apiKey`, `bearer`, `jwt`, `multiSession`, `sso`, `oauthProvider`, `oidcProvider`, `openAPI`, `genericOAuth`.
+
+Client plugins go in `createAuthClient({ plugins: [...] })`.
+
+---
+
+## Client
+
+Import from: `better-auth/client` (vanilla), `better-auth/react`, `better-auth/vue`, `better-auth/svelte`, `better-auth/solid`.
+
+Key methods: `signUp.email()`, `signIn.email()`, `signIn.social()`, `signOut()`, `useSession()`, `getSession()`, `revokeSession()`, `revokeSessions()`.
+
+---
+
+## Type Safety
+
+Infer types: `typeof auth.$Infer.Session`, `typeof auth.$Infer.Session.user`.
+
+For separate client/server projects: `createAuthClient<typeof auth>()`.
+
+---
+
+## Common Gotchas
+
+1. **Model vs table name** - Config uses ORM model name, not DB table name
+2. **Plugin schema** - Re-run CLI after adding plugins
+3. **Secondary storage** - Sessions go there by default, not DB
+4. **Cookie cache** - Custom session fields NOT cached, always re-fetched
+5. **Stateless mode** - No DB = session in cookie only, logout on cache expiry
+6. **Change email flow** - Sends to current email first, then new email
+
+---
+
+## Resources
+
+- [Docs](https://better-auth.com/docs)
+- [Options Reference](https://better-auth.com/docs/reference/options)
+- [LLMs.txt](https://better-auth.com/llms.txt)
+- [GitHub](https://github.com/better-auth/better-auth)
+- [Init Options Source](https://github.com/better-auth/better-auth/blob/main/packages/core/src/types/init-options.ts)

package/template/.agents/skills/checkpoint/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: checkpoint
+description: >
+  Create a comprehensive checkpoint commit with detailed analysis of all changes. Use this skill
+  when the user says "checkpoint", "commit everything", "save my progress", "create a commit",
+  or wants to stage and commit all current changes with a well-crafted message. Also use when
+  the user says "/checkpoint" or asks to snapshot current work. This skill stages all changes
+  and creates a descriptive commit — it does not push.
+---
+
+# Checkpoint Commit
+
+Create a checkpoint commit that captures all current changes — but only after the code passes lint, type check, and build.
+
+## Instructions
+
+### Step 1: Analyze Changes
+
+Run these commands to understand the full picture:
+
+1. `git status` — see all tracked and untracked files
+2. `git diff` — see detailed changes in tracked files
+3. `git diff --cached` — see already-staged changes
+4. `git log -5 --oneline` — understand this repo's commit message style
+
+### Step 2: Quality Checks
+
+Run all three checks. If any fail, fix the issues before proceeding — do not skip or ignore failures.
+
+1. `npm run lint` — fix any lint errors
+2. `npm run type-check` — fix any type errors (if the script doesn't exist, try `npx tsc --noEmit`)
+3. `npm run build` — fix any build errors
+
+Iterate until all three pass cleanly. Only then move to the next step.
+
+### Step 3: Stage Everything
+
+Stage all changes — tracked modifications, deletions, and new untracked files:
+
+```bash
+git add -A
+```
+
+### Step 4: Craft the Commit Message
+
+Write a commit message following the project's existing conventions (observed from `git log`). Structure:
+
+- **First line**: clear, concise summary in imperative mood (50-72 chars)
+  - Use conventional commit prefixes where the project uses them: `feat:`, `fix:`, `refactor:`, `docs:`, `chore:`, etc.
+- **Body** (separated by blank line): a short TL;DR of the changes — 1-3 sentences max. No bullet lists, no file-by-file breakdowns, no lengthy explanations.
+- **Footer**: co-author attribution
+
+### Step 5: Commit
+
+Create the commit using a heredoc for proper formatting:
+
+```bash
+git commit -m "$(cat <<'EOF'
+{first line}
+
+{tldr}
+
+Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+### Step 6: Report
+
+Display:
+- The commit hash and message summary
+- Files changed count
+- Insertions/deletions summary
+
+## Important
+
+- Stage and commit everything — do not skip files unless they are clearly sensitive (`.env`, credentials)
+- If the repo has no git history, run `git init` first
+- All quality checks (lint, type-check, build) MUST pass before committing — fix issues, don't skip them
+- Keep the commit body short — a TL;DR, not an essay
+- Follow the project's existing commit conventions (check the log first)
+- Do not push — only commit locally

package/template/.agents/skills/create-spec/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: create-spec
+description: >
+  Create a structured feature specification with self-contained task files organized into
+  parallel execution waves. Use this skill when the user says "create a spec", "plan this feature",
+  "write up an implementation plan", "break this into tasks", or after any planning conversation
+  where the user wants to capture decisions as actionable spec files. Also use when the user
+  says "/create-spec" or wants to decompose a feature into work items that agents can implement
+  independently. This skill produces local spec files under specs/{feature}/ — no GitHub integration.
+---
+
+# Create Feature Specification
+
+Transform a planning conversation into a structured spec folder that enables parallel agent implementation. The spec breaks a feature into self-contained task files — each one detailed enough that a coder agent can pick it up cold and implement it without reading anything else.
+
+The key insight: implementation plans that live in a single file are either too large for a context window or too shallow for independent execution. By splitting into one file per task with full context in each, we enable multiple agents to work in parallel while keeping each agent's context focused.
+
+## When to Use
+
+- After a planning conversation where requirements and technical details have been discussed
+- When the user asks to create a spec, plan a feature, or break work into tasks
+- When the user wants to prepare work for parallel agent implementation
+
+## Instructions
+
+### Step 1: Gather Requirements
+
+If the conversation already contains planning context (requirements discussed, technical decisions made, architecture outlined), extract all of it. Review the entire conversation to ensure nothing is lost — the spec is the single source of truth, and anything not captured here disappears.
+
+If no planning conversation exists, interview the user:
+- What does this feature do and why does it matter?
+- What are the acceptance criteria?
+- What technical constraints or decisions have been made?
+- What files, APIs, schemas, or patterns are involved?
+
+### Step 2: Name the Feature
+
+Choose a kebab-case name that clearly identifies the feature (e.g., `add-user-auth`, `migrate-to-postgres`, `dashboard-redesign`). This becomes the folder name under `specs/`.
+
+### Step 3: Decompose into Tasks
+
+Break the implementation into atomic tasks. Each task should:
+- Be completable in a single coding session by one agent
+- Have a clear, specific scope (one concern per task)
+- Produce working, testable code when complete
+- Not overlap in files modified with other tasks in the same wave
+
+Think carefully about granularity. Too coarse and agents can't work in parallel. Too fine and the overhead of context-switching between tasks dominates. A good task typically creates or modifies 1-5 files around a single concern.
+
+Do NOT include testing tasks (unit tests, e2e tests) unless the user explicitly asks for them.
+
+### Step 4: Build the Dependency Graph
+
+For each task, identify:
+- **What it depends on**: which tasks must complete before this one can start
+- **What depends on it**: which tasks are blocked until this one finishes
+
+Tasks with no dependencies form Wave 1. Tasks whose dependencies are all in Wave 1 form Wave 2. And so on. All tasks within a wave can execute in parallel.
+
+When assigning waves, verify that tasks within the same wave do not modify overlapping files. If two tasks in the same wave would touch the same file, move one to a later wave — parallel agents on the same branch cannot safely modify the same file.
+
+### Step 5: Create the Spec Folder
+
+Create the following structure at `specs/{feature-name}/`:
+
+```
+specs/{feature-name}/
+├── README.md
+├── requirements.md
+├── action-required.md
+└── tasks/
+    ├── task-01-{name}.md
+    ├── task-02-{name}.md
+    └── ...
+```
+
+Read the templates in `references/` before writing each file:
+- `references/readme-template.md` — for the README (dependency graph, wave table, status tracking)
+- `references/task-template.md` — for each task file (self-contained with all context)
+- `references/requirements-template.md` — for the requirements document
+- `references/action-required-template.md` — for manual human steps
+
+Task files are numbered with zero-padded two-digit prefixes in topological order: Wave 1 tasks first, then Wave 2, etc. Within a wave, order is arbitrary but stable.
+
+### Step 6: Write Self-Contained Task Files
+
+This is the most important step. Each task file is the **only thing** a coder agent will read before implementing. It must contain everything the agent needs:
+
+- **Description**: what to build and why it matters in context
+- **Dependency context**: what prior tasks produce that this task needs (summarized in prose, not just filenames). The agent should not need to read other task files.
+- **Technical details**: CLI commands, code snippets, schemas, file paths, env vars, API endpoints — every implementation-specific detail from the planning conversation
+- **Files to create/modify**: explicit list with purpose for each
+- **Acceptance criteria**: specific, verifiable conditions
+
+Review each task file with fresh eyes: could an agent who has never seen the planning conversation implement this correctly using only this file? If not, add what's missing.
+
+### Step 7: Extract Manual Actions
+
+Identify any steps that require human action (account creation, API key setup, DNS configuration, environment variables, third-party service registration, etc.). Write these to `action-required.md` grouped by timing (Before/During/After implementation). If none exist, note "No manual steps required."
+
+### Step 8: Report to User
+
+After creating the spec, display:
+
+```
+Feature specification created at specs/{feature-name}/
+
+Files created:
+- README.md (dependency graph, {N} waves, {T} tasks)
+- requirements.md
+- action-required.md
+- tasks/ ({T} task files)
+
+Wave breakdown:
+- Wave 1: {count} tasks (parallel) — {brief description}
+- Wave 2: {count} tasks (parallel) — {brief description}
+- ...
+
+Next steps:
+1. Review action-required.md for tasks you need to complete manually
+2. Review the requirements and task files
+3. Use /implement-feature to start parallel implementation
+```
+
+## Critical Rules
+
+- Every task file must be fully self-contained — this is the entire point of the spec structure. A coder agent reading only that file must know exactly what to do.
+- Capture ALL technical details from the planning conversation. The spec is the single source of truth — CLI commands, schemas, code snippets, file paths, env vars, API endpoints. Anything not captured here is lost.
+- Tasks within the same wave must not modify overlapping files. Parallel agents on the same branch cannot safely touch the same files.
+- Keep tasks atomic — one concern per task. If a task has more than 5-7 files to modify, consider splitting it.
+- Do not create testing tasks unless the user explicitly asks for them.
+- Number task files in topological order (wave 1 first, then wave 2, etc.) for easy scanning.

package/template/.agents/skills/create-spec/references/action-required-template.md

@@ -0,0 +1,53 @@
+# Action Required Template
+
+Use this structure for the action-required.md at the root of each spec folder. This file captures manual steps that require human action and cannot be automated by agents.
+
+## Template (when manual steps exist)
+
+```markdown
+# Action Required: {Feature Name}
+
+Manual steps that must be completed by a human. These cannot be automated.
+
+## Before Implementation
+
+- [ ] **{Action}** — {Brief reason why this is needed}
+- [ ] **{Action}** — {Brief reason}
+
+## During Implementation
+
+- [ ] **{Action}** — {Brief reason}
+
+## After Implementation
+
+- [ ] **{Action}** — {Brief reason}
+
+---
+
+> These tasks are also referenced in context within the relevant task files.
+```
+
+## Template (when no manual steps exist)
+
+```markdown
+# Action Required: {Feature Name}
+
+No manual steps required for this feature. All tasks can be implemented automatically.
+```
+
+## Common Manual Steps
+
+- Account creation (third-party services, OAuth apps)
+- API key generation and setup
+- Environment variable configuration
+- DNS or domain settings
+- Billing or subscription setup
+- Third-party service registration (webhooks, integrations)
+- Certificate provisioning
+- Access permissions or IAM roles
+
+## Key Points
+
+- Group actions by timing: before, during, and after implementation. This helps the user know when they need to act.
+- Keep descriptions brief — one line explaining what to do and why.
+- Also reference these manual steps in the relevant task files so agents know to pause or skip that part.

package/template/.agents/skills/create-spec/references/readme-template.md

@@ -0,0 +1,53 @@
+# README Template
+
+Use this structure for the README.md at the root of each spec folder. The README serves as the orchestration index — the `implement-feature` skill reads it to determine wave order, task assignments, and completion status.
+
+## Template
+
+```markdown
+# {Feature Name}
+
+## Overview
+
+{One paragraph summary of what the feature does and why it exists.}
+
+## Quick Links
+
+- [Requirements](./requirements.md) — full requirements and acceptance criteria
+- [Action Required](./action-required.md) — manual steps needing human action
+
+## Dependency Graph
+
+​```mermaid
+graph TD
+    task-01-name["01: Task Title"]
+    task-02-name["02: Task Title"]
+    task-03-name["03: Task Title"]
+    task-01-name --> task-03-name
+    task-02-name --> task-03-name
+​```
+
+## Waves
+
+| Wave | Tasks | Description |
+|------|-------|-------------|
+| 1 | task-01, task-02 | {Brief description of what this wave accomplishes} |
+| 2 | task-03 | {Brief description} |
+
+## Task Status
+
+### Wave 1
+- [ ] [task-01-{name}](./tasks/task-01-{name}.md) — {One-line title}
+- [ ] [task-02-{name}](./tasks/task-02-{name}.md) — {One-line title}
+
+### Wave 2
+- [ ] [task-03-{name}](./tasks/task-03-{name}.md) — {One-line title}
+```
+
+## Key Points
+
+- The **Dependency Graph** uses Mermaid syntax (widely rendered in GitHub, VS Code, etc.). Each node shows the task number and title for quick reference.
+- The **Waves** table provides a scannable overview of what runs in parallel.
+- The **Task Status** section uses markdown checkboxes that the `implement-feature` skill updates as tasks complete. The orchestrator parses these to determine which wave to resume from.
+- Links to task files use relative paths pointing into the `tasks/` subfolder.
+- Tasks without dependencies have no incoming arrows in the graph — these form Wave 1.

package/template/.agents/skills/create-spec/references/requirements-template.md

@@ -0,0 +1,54 @@
+# Requirements Template
+
+Use this structure for the requirements.md at the root of each spec folder.
+
+## Template
+
+```markdown
+# Requirements: {Feature Name}
+
+## Summary
+
+{What the feature does and why it exists — 2-3 paragraphs covering the problem, the solution, and the expected outcome.}
+
+## Goals
+
+- {Goal 1}
+- {Goal 2}
+- {Goal 3}
+
+## Non-Goals
+
+{Explicitly out of scope — things that might seem related but are not part of this feature.}
+
+- {Non-goal 1}
+- {Non-goal 2}
+
+## Acceptance Criteria
+
+{High-level criteria for the entire feature. Individual task files have their own granular criteria.}
+
+- [ ] {Criterion 1}
+- [ ] {Criterion 2}
+- [ ] {Criterion 3}
+
+## Assumptions
+
+{Things assumed to be true that could affect implementation if they turn out to be false.}
+
+- {Assumption 1}
+- {Assumption 2}
+
+## Technical Constraints
+
+{Architecture decisions, technology choices, or constraints that affect all tasks.}
+
+- {Constraint 1}
+- {Constraint 2}
+```
+
+## Key Points
+
+- The requirements doc provides **overall feature context** that each coder agent receives alongside its task file. Keep it focused on the "what" and "why" — individual task files handle the "how."
+- Non-goals are important: they prevent agents from over-building. If search functionality is out of scope, say so — otherwise a well-meaning agent might add it.
+- Acceptance criteria here are feature-level (the whole thing works end-to-end). Task-level criteria live in each task file.

package/template/.agents/skills/create-spec/references/task-template.md

@@ -0,0 +1,79 @@
+# Task File Template
+
+Use this structure for each task file in the `tasks/` subfolder. Each task file must be **fully self-contained** — a coder agent reading only this file should know exactly what to implement, why, and how.
+
+## Template
+
+```markdown
+# Task {nn}: {Title}
+
+## Status
+
+pending
+
+## Wave
+
+{N}
+
+## Description
+
+{2-5 sentences describing what this task accomplishes and why it matters in the context of the overall feature. Include enough context that an agent unfamiliar with the planning conversation understands the purpose.}
+
+## Dependencies
+
+**Depends on:** {Comma-separated list of task filenames, or "None (Wave 1)"}
+**Blocks:** {Comma-separated list of task filenames, or "None"}
+
+**Context from dependencies:** {Prose summary of what the dependency tasks produce that this task needs. For example: "task-01-setup-database.md creates the PostgreSQL schema with users and sessions tables. This task builds the API routes that query those tables." This is what makes each file self-contained — the agent does not need to read other task files to understand its inputs.}
+
+## Files to Create
+
+- `path/to/new-file.ts` — {Brief purpose}
+- `path/to/another-file.ts` — {Brief purpose}
+
+## Files to Modify
+
+- `path/to/existing-file.ts` — {What changes and why}
+
+## Technical Details
+
+{All implementation-specific details from the planning conversation. This section is the single source of truth. Include:}
+
+### Implementation Steps
+
+1. {Step-by-step instructions with enough detail for independent implementation}
+2. {Include CLI commands where relevant: `pnpm add package-name`}
+3. {Include code snippets for non-obvious patterns}
+
+### Code Snippets
+
+{Key type definitions, schemas, configuration blocks, or patterns that the implementer needs. Use fenced code blocks with language tags.}
+
+### Environment Variables
+
+{If applicable:}
+- `VAR_NAME` — {Purpose and example value}
+
+### API Endpoints
+
+{If applicable:}
+- `METHOD /path` — {Request/response shape}
+
+## Acceptance Criteria
+
+- [ ] {Criterion 1 — specific and verifiable}
+- [ ] {Criterion 2}
+- [ ] {Criterion 3}
+
+## Notes
+
+{Any additional context, edge cases, warnings, or architectural decisions relevant to this task. Omit this section if there's nothing to add.}
+```
+
+## Key Points
+
+- The **Status** field is updated by the `implement-feature` skill: `pending` → `in-progress` → `complete`.
+- The **Dependencies** section includes prose context (not just filenames) so the agent understands its inputs without reading other files. This is the most important part of making task files self-contained.
+- **Files to Create** and **Files to Modify** make the task's scope explicit. Tasks in the same wave should not overlap on these lists.
+- **Technical Details** captures everything from the planning conversation — CLI commands, schemas, code snippets, file paths, env vars, API endpoints. If it was discussed during planning and is relevant to this task, it belongs here.
+- **Acceptance Criteria** should be specific enough that completion can be verified objectively (by a code review agent or a human).