@webpresso/agent-kit 0.21.0

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

@@ -0,0 +1,212 @@
+---
+type: skill
+slug: better-auth-best-practices
+title: Better Auth Integration Guide
+status: active
+scope: repo
+applies_to: [agents]
+related: []
+created: '2026-05-07'
+last_reviewed: '2026-05-07'
+name: better-auth-best-practices
+description: Skill for integrating Better Auth - the comprehensive TypeScript authentication framework.
+upstream: 
+  source: null
+  last_synced: "2026-04-22"
+---
+
+# Better Auth Integration Guide
+
+**Always consult [better-auth.com/docs](https://better-auth.com/docs) for code examples and latest API.**
+
+Better Auth is a TypeScript-first, framework-agnostic auth framework supporting email/password, OAuth, magic links, passkeys, and more via plugins.
+
+---
+
+## 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
+
+- `just better-auth-cli migrate` - Apply schema (built-in adapter)
+- `just better-auth-cli generate` - Generate schema for Prisma/Drizzle
+- `just better-auth-cli mcp --cursor` - Add MCP to AI tools
+
+**Re-run after adding/changing plugins.**
+
+**Note**: Always use the dedicated `just better-auth-cli ...` wrapper for these commands so agents do not invoke package-manager CLIs directly.
+
+---
+
+## 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
+7. **Cloudflare Workers: never call `betterAuth()` per request** — `betterAuth()` initializes the plugin registry, Drizzle adapter, and JWKS cache. In Workers, the same isolate handles many requests; calling it per request is wasteful. Use a module-level `WeakMap` keyed on the stable `env` object:
+
+   ```ts
+   // ❌ Wrong — re-initializes on every request
+   app.all('/auth/*', async (c) => {
+     const auth = betterAuth(buildConfig(c.env))
+     return auth.handler(c.req.raw)
+   })
+
+   // ✅ Correct — one instance per isolate
+   const authInstances = new WeakMap<object, Auth<BetterAuthOptions>>()
+   app.all('/auth/*', async (c) => {
+     let auth = authInstances.get(c.env as object)
+     if (!auth) {
+       auth = betterAuth(buildConfig(c.env)) as Auth<BetterAuthOptions>
+       authInstances.set(c.env as object, auth)
+     }
+     return auth.handler(c.req.raw)
+   })
+   ```
+
+   The `WeakMap` is GC-safe: when the isolate is collected the map is collected with it. The cast to `Auth<BetterAuthOptions>` is required when `buildConfig` returns a narrower type (e.g. with required `basePath`).
+8. **`organization()` plugin + teams** — calling `organization()` with no options enables teams by default in v1.6.9+, which produces `Auth` generic type incompatible with `DefaultOrganizationPlugin<OrganizationOptions>`. Pass `{ teams: { enabled: false } }` explicitly to match the expected type.
+9. **`deviceAuthorization()` requires `schema: {}`** — Better Auth v1.6.9 Zod validates `schema` as non-optional. Call as `deviceAuthorization({ schema: {} })`; calling it bare throws at startup.
+
+---
+
+## Resources
+
+- [Docs](https://better-auth.com/docs)
+- [Options Reference](https://better-auth.com/docs/system/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/skills/deep-research/SKILL.md

@@ -0,0 +1,240 @@
+---
+type: skill
+slug: deep-research
+title: Deep Research
+status: active
+scope: repo
+applies_to: [agents]
+related: []
+created: '2026-05-07'
+last_reviewed: '2026-05-07'
+name: deep-research
+description: Deep web research with credible pro/con sentiment, 2026 best practices, project vision alignment analysis, and timestamped output to docs/research/
+argument-hint: "<subject or question to research>"
+---
+
+<Purpose>
+Deep Research is a multi-phase web research workflow that produces a balanced, citation-backed analysis of a subject. It collects both positive and negative sentiments from credible sources, evaluates alignment with the project's vision and tech stack, identifies 2026 state-of-the-art best practices, and logs the result to `docs/research/` with a date-prefixed filename.
+</Purpose>
+
+<Use_When>
+- Evaluating a technology, library, pattern, or product direction
+- Comparing alternatives before making an architectural or product decision
+- The user says "research", "deep research", "investigate", or "what does the community think about"
+- You need a balanced view of trade-offs before recommending something
+</Use_When>
+
+<Do_Not_Use_When>
+- The user wants a quick factual lookup (use WebSearch directly)
+- The user wants codebase exploration (use explore)
+- The user wants a requirements interview (use deep-interview)
+- The answer is already well-established and non-controversial
+</Do_Not_Use_When>
+
+<Output_Contract>
+A single markdown file written to:
+
+```
+docs/research/{YYYY-MM-DD}-{slug}.md
+```
+
+Where `{YYYY-MM-DD}` is today's date and `{slug}` is a kebab-case summary of the subject.
+
+The file MUST have this frontmatter and structure (see Phase 5 for full template).
+</Output_Contract>
+
+<Steps>
+
+## Phase 0: Scope and Context Load
+
+1. Parse `{{ARGUMENTS}}` into a research subject and any qualifiers (e.g., "for our use case", "vs X").
+2. Derive a short kebab-case slug for the filename.
+3. Read `docs/research/product/VISION.md` (or the project's equivalent — check `docs/` for a vision doc) to load the current vision context. Skip if not present.
+4. Identify the relevant tech stack context by reading project config files (e.g., `package.json` workspaces, `tsconfig.json`, key dependencies) — keep this lightweight, just enough to judge alignment.
+5. Announce the research plan to the user:
+   - Subject
+   - Key questions to investigate
+   - Output path
+
+## Phase 1: Broad Discovery (parallel)
+
+Run **5-8 parallel WebSearch queries** covering different angles:
+
+1. **Overview**: `"{subject} 2026 overview best practices"`
+2. **Positive sentiment**: `"{subject} benefits advantages why use 2026"`
+3. **Negative sentiment / criticism**: `"{subject} problems criticism drawbacks 2026"`
+4. **Community opinion**: `"{subject} reddit hacker news experience production 2026"`
+5. **Comparison / alternatives**: `"{subject} vs alternatives comparison 2026"`
+6. **State of the art**: `"{subject} state of the art latest 2026"`
+7. **(If applicable)** Stack-specific: `"{subject} TypeScript Cloudflare Workers React 2026"`
+8. **(If applicable)** Domain-specific query based on the project's problem space
+
+For each search, record:
+- Source URL
+- Source type (docs, blog, forum, official, academic)
+- Key claims or data points
+- Sentiment direction (positive / negative / neutral)
+
+## Phase 2: Deep Dive (sequential, selective)
+
+From Phase 1 results, identify the **5-10 most credible and information-dense sources**.
+
+Use `WebFetch` on each to extract deeper detail. Prioritize:
+- Official documentation or announcements
+- Production experience reports (postmortems, migration stories)
+- Benchmark data or technical comparisons
+- Strong critical takes with specific evidence
+
+For each fetched source, extract:
+- Specific claims with evidence
+- Sentiment and strength (strong positive, mild positive, neutral, mild negative, strong negative)
+- Credibility assessment (official docs > production experience > blog opinion > forum anecdote)
+
+## Phase 3: Triangulate and Score
+
+1. **Cluster findings** into themes (e.g., "developer experience", "performance", "ecosystem maturity", "production readiness").
+2. **Cross-reference claims**: if only one source makes a claim, flag it as unverified. Claims supported by 2+ independent sources get higher weight.
+3. **Score source credibility** using:
+   - Official docs / specs: high
+   - Production postmortems with data: high
+   - Respected engineering blogs: medium-high
+   - Community forums (HN, Reddit) with detail: medium
+   - Marketing material / vendor blogs: low (note bias)
+   - Undated or anonymous content: very low
+4. **Identify gaps**: what questions remain unanswered? If critical gaps exist, run 1-2 additional targeted searches.
+
+## Phase 4: Vision and Stack Alignment Analysis
+
+Using the project's vision from Phase 0 and the research findings:
+
+1. **Vision alignment**: How does this subject relate to the project's stated mission? Does it help or hinder current priorities?
+2. **Tech stack fit**: How well does this integrate with the existing stack (read `package.json`, key deps, framework choices)? What's the integration cost?
+3. **Trade-off assessment**: Given the project's current stage, what are the most relevant trade-offs?
+4. **Recommendation**: Based on the evidence, what's the suggested path? Be explicit about confidence level.
+
+## Phase 5: Write Report
+
+Write the report to `docs/research/{YYYY-MM-DD}-{slug}.md` using this template:
+
+```markdown
+---
+type: research
+title: "{Title}"
+subject: "{subject}"
+date: {YYYY-MM-DD}
+confidence: {high|medium|low}
+verdict: {adopt|trial|assess|hold|reject}
+---
+
+# {Title}
+
+> One-line summary of the finding.
+
+## TL;DR
+
+3-5 bullet executive summary covering: what it is, key finding, recommendation.
+
+## What This Is
+
+Brief neutral description of the subject being researched.
+
+## State of the Art (2026)
+
+Current best practices, latest developments, where the ecosystem stands today.
+Cite sources inline as [Source Name](url).
+
+## Positive Signals
+
+Evidence-backed reasons in favor. Group by theme.
+Each point should cite its source and note credibility level.
+
+### {Theme 1}
+- ...
+
+### {Theme 2}
+- ...
+
+## Negative Signals
+
+Evidence-backed criticism and risks. Group by theme.
+Each point should cite its source and note credibility level.
+
+### {Theme 1}
+- ...
+
+### {Theme 2}
+- ...
+
+## Community Sentiment
+
+What practitioners actually say. Include direct quotes where available.
+Note the balance: if sentiment skews one way, say so explicitly.
+
+## Project Alignment
+
+### Vision Fit
+How this relates to the project's current goals.
+
+### Tech Stack Fit
+Integration with the project's stack (from `package.json`, framework configs).
+
+### Trade-offs for Current Stage
+What matters most given where the project is now.
+
+## Recommendation
+
+Clear recommendation with confidence level and reasoning.
+Include conditions under which the recommendation would change.
+
+## Sources
+
+Numbered list of all sources used, with:
+- [N] [Title](url) — type, credibility, sentiment direction
+```
+
+## Phase 6: Present Summary
+
+After writing the file, present to the user:
+1. The output file path
+2. The verdict and confidence
+3. A 3-line summary of the key finding
+4. Any critical gaps or caveats
+
+</Steps>
+
+<Quality_Gates>
+- Minimum 8 distinct sources cited
+- At least 2 sources per major claim
+- Both positive AND negative signals sections must be substantive (not token)
+- Sources section must include credibility and sentiment annotations
+- Vision alignment section must reference specific project goals (not generic)
+- All inline citations must be clickable links
+- Frontmatter must include confidence and verdict fields
+</Quality_Gates>
+
+<Verdict_Scale>
+- **adopt**: Strong evidence, clear fit, community consensus positive. Use it.
+- **trial**: Promising evidence, worth a bounded experiment. Try it in a limited scope.
+- **assess**: Mixed signals or insufficient evidence. Research more before committing.
+- **hold**: Significant concerns or poor fit. Don't invest now, revisit later.
+- **reject**: Clear evidence against. Don't use this.
+</Verdict_Scale>
+
+<Tool_Usage>
+- `WebSearch` for broad discovery (Phase 1) and gap-filling (Phase 3)
+- `WebFetch` for deep source extraction (Phase 2)
+- `Read` for loading vision and tech stack context (Phase 0)
+- `Write` for the final report (Phase 5)
+- `Agent` with `subagent_type=Explore` if codebase context is needed for alignment analysis
+- Use parallel tool calls wherever searches are independent
+</Tool_Usage>
+
+<Common_Mistakes>
+- Writing a report that's all positive or all negative — always find both sides
+- Citing marketing material as if it were neutral evidence — flag vendor bias
+- Making alignment claims without reading the actual vision doc
+- Using stale search results — always include "2026" in queries
+- Writing the report before triangulating — don't just concatenate search results
+</Common_Mistakes>
+
+Task: {{ARGUMENTS}}

package/skills/fix/SKILL.md

@@ -0,0 +1,120 @@
+---
+type: skill
+slug: fix
+title: Fix
+status: active
+scope: repo
+applies_to: [agents]
+related: [verify, systematic-debugging, test-driven-development]
+created: '2026-05-13'
+last_reviewed: '2026-05-22'
+name: fix
+description: Root-cause fix workflow for debugging and implementation. Use when the user asks to fix an issue, bug, failing test, error, broken behavior, or asks for `/fix <target>` / `$fix <target>`. Enforces root-cause analysis, minimal correct changes, regression tests, and scoped verification before claiming done.
+argument-hint: '<target> where target is: file|symptom|error|test|"free-text description"'
+---
+
+# Fix Command
+
+Fix the issue at its root, future-proof, aligned with repo philosophy.
+
+**Arguments**: $ARGUMENTS
+
+This command turns "please fix it well" into an enforceable workflow: reproduce, identify the broken invariant, repair it at the owner, prove the repair, and escalate to `/verify` when the blast radius is broader than a local fix.
+
+## Non-negotiable invariants
+
+1. **Root cause, not symptom.** Trace the failure to the invariant that actually broke. Do not patch callers when the owner is fixable.
+2. **Loud failures, no silent fallbacks.** No default shims, sentinel returns, or catch-and-continue behavior that hides missing config, bad state, or broken boundaries.
+3. **Use the repo's real execution surface.** Prefer repo-owned wrappers and injected routing guidance over host-specific tool assumptions. If the repo exposes quality wrappers, use them. If context-mode routing is injected, follow it for large-output inspection.
+4. **Regression proof is mandatory.** Add or strengthen a test or other reliable proof that would fail against the old behavior.
+5. **Raising timeouts is not a fix.** If a timeout fires, investigate the bottleneck. Only raise a bound when the repo already documents that workload and you can cite measurement.
+6. **Zero suppressions, zero papering over.** No lint disables, ts-ignore, compat aliases, or "temporary" branches to sneak the fix through.
+7. **Minimal correct diff.** Update every consumer of a changed contract in the same change, but do not bundle unrelated cleanup.
+
+## Protocol
+
+### Step 1 — Reproduce and name the broken invariant
+
+- Run the exact command, test, or user flow that surfaces the failure.
+- Capture the evidence that matters: error text, file:line, exit code, failing assertion, or log path.
+- Read enough surrounding code to say the broken invariant in one sentence.
+- If the issue is nondeterministic, gather evidence until you can describe the slow/flaky/failing case without guessing.
+
+If the "issue" is actually several unrelated failures, stop and ask which one to fix first.
+
+### Step 2 — Decide where the fix belongs
+
+State briefly:
+
+- the broken invariant
+- the owner that should enforce it
+- whether the fix changes a public contract
+- which direct consumers must change in the same diff
+
+If the blast radius is broader than the owner + direct consumers, keep going with `/fix` only if the change is still one coherent repair. If the work becomes a broader hardening pass, plan a `/verify` handoff before claiming done.
+
+### Step 3 — Write failing proof first when feasible
+
+- For a reproducible bug, write or strengthen the smallest regression test that fails on the old behavior.
+- Verify that it fails for the right reason before changing production code.
+- If test-first is genuinely infeasible at that boundary, record why and create the nearest reliable proof instead (for example a deterministic integration reproduction, fixture, or logged command).
+
+Do not keep production code written before the test as "reference". If you wrote code first, throw it away and restart from the failing proof.
+
+### Step 4 — Implement the minimal correct fix
+
+- Edit the file or module that owns the invariant.
+- Update every changed consumer in the same diff. No half-migrations.
+- Delete compat shims, dead aliases, and TODO branches made obsolete by the repair.
+- Keep complexity down by extracting helpers instead of nesting conditionals.
+
+### Step 5 — Run scoped verification
+
+Run the narrowest checks that prove the repaired behavior on the real repo surface:
+
+- targeted test(s) for the repaired path
+- targeted lint/typecheck/build checks for changed files or packages
+- any boundary-specific verification the repo requires for the touched surface
+
+Rules:
+
+- Prefer repo-owned wrappers or routed quality tools over raw host-specific commands.
+- Reuse fresh logs if the repo auto-saves them; do not re-run long commands just to re-read output.
+- Read the exit code and summary before making a claim.
+
+Escalate to `/verify <target>` when any of these are true:
+
+- the fix crosses packages
+- the fix changes a public or shared contract
+- the fix touched docs, plans, blueprints, or repo SSOT
+- the fix needs dead-code / compat / broad regression review before claiming done
+
+### Step 6 — Report with evidence
+
+Keep it short:
+
+- what invariant broke
+- how the change restores it
+- what proof ran (tests, commands, log paths, exit codes)
+- adjacent issues noticed but intentionally not fixed
+
+## Done looks like
+
+- [ ] Root cause named in one sentence
+- [ ] Fix applied at the owning boundary
+- [ ] Regression proof fails against the old behavior
+- [ ] Minimal code change restores the invariant
+- [ ] Scoped verification passed on the changed surface
+- [ ] `/verify` handoff used when blast radius exceeded a local fix
+- [ ] Report cites evidence, not intent
+
+## Anti-patterns this command refuses
+
+- Fixing the nearest symptom while leaving the real invariant broken
+- Catching an error and returning a sentinel to "keep things moving"
+- Raising a timeout, retry count, or polling interval instead of finding the bottleneck
+- Adding a deprecated alias instead of updating consumers
+- Introducing `any`, suppressions, or lint disables to unblock the fix
+- Bundling unrelated refactors with the repair
+- Claiming done from intuition, partial output, or another agent's success message
+- Writing a planning/doc artifact when the user asked for a fix