@ngxtm/devkit 3.7.0 → 3.9.0

package/merged-commands/best-practices.md

@@ -0,0 +1,500 @@
+---
+name: best-practices
+description: >-
+  Transforms vague prompts into optimized Claude Code prompts. Adds verification,
+  specific context, constraints, and proper phasing. Invoke with /best-practices.
+---
+
+# Best Practices — Prompt Transformer
+
+> Transform prompts by adding what Claude needs to succeed.
+
+## Start Here
+
+Based on user's request:
+
+**User provides a prompt to transform:**
+→ Ask using AskUserQuestion:
+  - **Question:** "How should I improve this prompt?"
+  - **Header:** "Mode"
+  - **Options:**
+    1. **Transform directly** — "I'll apply best practices and output an improved version"
+    2. **Build context first** — "I'll gather codebase context and intent analysis first"
+
+**User asks to learn/understand:**
+→ Show the 5 Transformation Principles section
+
+**User asks for examples:**
+→ Link to references/before-after-examples.md
+
+**User asks to evaluate a prompt:**
+→ Use the Success Criteria eval rubric at the end of this document
+
+---
+
+## If "Transform directly"
+
+Apply the 5 principles below and output the improved prompt immediately.
+
+## If "Build context first"
+
+Launch 3 parallel agents to gather context:
+
+```
+Run these agents IN PARALLEL using the Task tool:
+
+- Task task-intent-analyzer("[user's prompt]")
+- Task best-practices-referencer("[user's prompt]")
+- Task codebase-context-builder("[user's prompt]")
+```
+
+### What Each Agent Returns
+
+| Agent | Mission | Returns |
+|-------|---------|---------|
+| **task-intent-analyzer** | Understand what user is trying to do | Task type, gaps, edge cases, transformation guidance |
+| **best-practices-referencer** | Find relevant patterns from references/ | Matching examples, anti-patterns to avoid, transformation rules |
+| **codebase-context-builder** | Explore THIS codebase | Specific file paths, similar implementations, conventions |
+
+### After Agents Return
+
+1. **Synthesize findings** — Combine intent + best practices + codebase context
+2. **Apply matching patterns** — Use examples from best-practices-referencer as templates
+3. **Ground in codebase** — Add specific file paths from codebase-context-builder
+4. **Transform the prompt** — Apply the 5 principles with all gathered context
+5. **Output** — Show improved prompt with before/after comparison
+
+### Agent Definitions
+
+The agents are defined in `agents/`:
+- `agents/task-intent-analyzer.md` — Analyzes intent, gaps, and edge cases
+- `agents/best-practices-referencer.md` — Finds relevant examples and patterns from references/
+- `agents/codebase-context-builder.md` — Explores codebase for files and conventions
+
+---
+
+## Transformation Workflow
+
+When transforming (after mode selection):
+
+1. **Identify what's missing** — Check against the 5 principles below
+2. **Add missing elements** — Verification, context, constraints, phases, rich content
+3. **Output the improved prompt** — In a code block, ready to copy-paste
+4. **Show what changed** — Brief comparison of before/after
+
+---
+
+## The 5 Transformation Principles
+
+Apply these in order of priority:
+
+### 1. Add Verification (Highest Priority)
+
+**The single highest-leverage improvement.** Claude performs dramatically better when it can verify its own work.
+
+| Missing | Add |
+|---------|-----|
+| No success criteria | Test cases with expected inputs/outputs |
+| UI changes | "take screenshot and compare to design" |
+| Bug fixes | "write a failing test, then fix it" |
+| Build issues | "verify the build succeeds after fixing" |
+| Refactoring | "run the test suite after each change" |
+| No root cause enforcement | "address root cause, don't suppress error" |
+| No verification report | "summarize what you ran and what passed" |
+
+```
+BEFORE: "implement email validation"
+AFTER:  "write a validateEmail function. test cases: user@example.com → true,
+         invalid → false, user@.com → false. run the tests after implementing"
+```
+
+```
+BEFORE: "fix the API error"
+AFTER:  "the /api/orders endpoint returns 500 for large orders. check
+         OrderService.ts for the error. address the root cause, don't suppress
+         the error. after fixing, run the test suite and summarize what passed
+         and what you verified."
+```
+
+### 2. Provide Specific Context
+
+Replace vague references with precise locations and details.
+
+| Vague | Specific |
+|-------|----------|
+| "the code" | `src/auth/login.ts` |
+| "the bug" | "users report X happens when Y" |
+| "the API" | "the /api/users endpoint in routes.ts" |
+| "that function" | `processPayment()` on line 142 |
+
+**Four ways to add context:**
+
+| Strategy | Example |
+|----------|---------|
+| **Scope the task** | "write a test for foo.py covering the edge case where user is logged out. avoid mocks." |
+| **Point to sources** | "look through ExecutionFactory's git history and summarize how its API evolved" |
+| **Reference patterns** | "look at HotDogWidget.php and follow that pattern for the calendar widget" |
+| **Describe symptoms** | "users report login fails after session timeout. check src/auth/, especially token refresh" |
+
+**Respect Project CLAUDE.md:**
+
+If the project has a CLAUDE.md, the transformed prompt should:
+- Not contradict project conventions
+- Reference project-specific patterns when relevant
+- Note any project constraints that apply
+
+```
+BEFORE: "add a new API endpoint"
+AFTER:  "add a GET /api/products endpoint. check CLAUDE.md for API conventions
+         in this project. follow the pattern in routes/users.ts. run the API
+         tests after implementing."
+```
+
+```
+BEFORE: "fix the login bug"
+AFTER:  "users report login fails after session timeout. check the auth flow
+         in src/auth/, especially token refresh. write a failing test that
+         reproduces the issue, then fix it"
+```
+
+### 3. Add Constraints
+
+Tell Claude what NOT to do. Prevents over-engineering and unwanted changes.
+
+| Constraint Type | Examples |
+|-----------------|----------|
+| **Dependencies** | "no new libraries", "only use existing deps" |
+| **Testing** | "avoid mocks", "use real database in tests" |
+| **Scope** | "don't refactor unrelated code", "only touch auth module" |
+| **Approach** | "address root cause, don't suppress error", "keep backward compat" |
+| **Patterns** | "follow existing codebase conventions", "match the style in utils.ts" |
+
+```
+BEFORE: "add a calendar widget"
+AFTER:  "implement a calendar widget with month selection and year pagination.
+         follow the pattern in HotDogWidget.php. build from scratch without
+         libraries other than the ones already used in the codebase"
+```
+
+### 4. Structure Complex Tasks in Phases
+
+For larger tasks, separate exploration from implementation.
+
+**The 4-Phase Pattern:**
+
+```
+Phase 1: EXPLORE
+"read src/auth/ and understand how we handle sessions and login.
+ also look at how we manage environment variables for secrets."
+
+Phase 2: PLAN
+"I want to add Google OAuth. What files need to change?
+ What's the session flow? Create a plan."
+
+Phase 3: IMPLEMENT
+"implement the OAuth flow from your plan. write tests for the
+ callback handler, run the test suite and fix any failures."
+
+Phase 4: COMMIT
+"commit with a descriptive message and open a PR"
+```
+
+**When to use phases:**
+- Uncertain about the approach
+- Change modifies multiple files
+- Unfamiliar with the code being modified
+
+**Skip phases when:**
+- Could describe the diff in one sentence
+- Fixing a typo, adding a log line, renaming a variable
+
+```
+BEFORE: "add OAuth"
+AFTER:  "read src/auth/ and understand current session handling. create a plan
+         for adding OAuth. then implement following the plan. write tests and
+         verify they pass"
+```
+
+### 5. Include Rich Content
+
+Provide supporting materials that Claude can use directly.
+
+| Content Type | How to Provide |
+|--------------|----------------|
+| **Files** | Use `@filename` to reference files |
+| **Images** | Paste screenshots directly |
+| **Errors** | Paste actual error messages, not descriptions |
+| **Logs** | Pipe with `cat error.log \| claude` |
+| **URLs** | Link to relevant documentation |
+
+```
+BEFORE: "make the dashboard look better"
+AFTER:  "[paste screenshot] implement this design for the dashboard.
+         take a screenshot of the result and compare it to the original.
+         list any differences and fix them. ensure responsive behavior
+         at 768px and 1024px breakpoints"
+```
+
+```
+BEFORE: "the build is failing"
+AFTER:  "the build fails with this error: [paste actual error]. fix it
+         and verify the build succeeds. address the root cause, don't
+         suppress the error"
+```
+
+---
+
+## Output Format
+
+When transforming a prompt, output:
+
+```markdown
+**Original:** [their prompt]
+
+**Improved:**
+```
+[transformed prompt in code block]
+```
+
+**Added:**
+- [what was missing and added]
+- [another improvement]
+- [etc.]
+```
+
+---
+
+## Quick Transformation Examples
+
+### Bug Fix
+```
+BEFORE: "fix the login bug"
+
+AFTER: "users report login fails after session timeout. check the auth flow
+in src/auth/, especially token refresh. write a failing test that reproduces
+the issue, then fix it. verify by running the auth test suite."
+
+ADDED: symptom, location, verification (failing test), success criteria
+```
+
+### Feature Implementation
+```
+BEFORE: "add a search feature"
+
+AFTER: "implement search for the products page. look at how filtering works
+in ProductList.tsx for the pattern. search should filter by name and category.
+add tests for: empty query returns all, partial match works, no results shows
+message. no external search libraries."
+
+ADDED: location, reference pattern, specific behavior, test cases, constraint
+```
+
+### Refactoring
+```
+BEFORE: "make the code better"
+
+AFTER: "refactor utils.js to use ES2024 features while maintaining the same
+behavior. specifically: convert callbacks to async/await, use optional
+chaining, add proper TypeScript types. run the existing test suite after
+each change to ensure nothing breaks."
+
+ADDED: specific changes, constraint (same behavior), verification after each step
+```
+
+### Testing
+```
+BEFORE: "add tests for foo.py"
+
+AFTER: "write tests for foo.py covering the edge case where the user is
+logged out. avoid mocks. use the existing test patterns in tests/. test
+cases: logged_out_user returns 401, expired_session redirects to login,
+invalid_token raises AuthError."
+
+ADDED: specific edge case, constraint (no mocks), pattern reference, test cases
+```
+
+### Debugging
+```
+BEFORE: "the API is slow"
+
+AFTER: "the /api/orders endpoint takes 3+ seconds. profile the database
+queries in OrderService.ts. look for N+1 queries or missing indexes.
+fix the performance issue and verify response time is under 500ms."
+
+ADDED: specific endpoint, location, what to look for, measurable success criteria
+```
+
+### UI Changes
+```
+BEFORE: "fix the button styling"
+
+AFTER: "[paste screenshot of design] update the primary button to match this
+design. check Button.tsx and the theme in tailwind.config.js. take a
+screenshot after changes and compare to the design. list any differences."
+
+ADDED: design reference, file locations, visual verification
+```
+
+### Exploration
+```
+BEFORE: "how does auth work?"
+
+AFTER: "read src/auth/ and explain how authentication works in this codebase.
+cover: how sessions are created, how tokens are refreshed, where secrets
+are stored. summarize in a markdown doc."
+
+ADDED: specific files, specific questions to answer, output format
+```
+
+### Migration
+```
+BEFORE: "upgrade to React 18"
+
+AFTER: "migrate from React 17 to React 18. first, read the migration guide
+at [URL]. then identify all components using deprecated APIs. update one
+component at a time, running tests after each. don't change unrelated code."
+
+ADDED: phased approach, reference docs, incremental verification, scope constraint
+```
+
+### With Verification Report
+```
+BEFORE: "fix the API error"
+
+AFTER: "the /api/orders endpoint returns 500 for large orders. check
+OrderService.ts for the error. address the root cause, don't suppress
+the error. after fixing, run the test suite and summarize what passed
+and what you verified."
+
+ADDED: symptom, location, root cause enforcement, verification report
+```
+
+---
+
+## Transformation Checklist
+
+Before outputting, verify the improved prompt has:
+
+- [ ] **Verification** — How to know it worked (tests, screenshot, output)
+- [ ] **Location** — Specific files, functions, or areas
+- [ ] **Constraints** — What NOT to do
+- [ ] **Single task** — Not compound (split if needed)
+- [ ] **Phases** — If complex, structured as explore → plan → implement
+- [ ] **Root cause** — For bugs: "address root cause, don't suppress"
+- [ ] **CLAUDE.md** — Respect project conventions if they exist
+
+---
+
+## Quick Prompt Quality Check
+
+Rate the prompt against these dimensions:
+
+| Dimension | 0 (Missing) | 1 (Partial) | 2 (Complete) |
+|-----------|-------------|-------------|--------------|
+| **Verification** | None | "test it" | Specific test cases + report |
+| **Location** | "the code" | "auth module" | `src/auth/login.ts:42` |
+| **Constraints** | None | Implied | "avoid X, no Y, root cause only" |
+| **Scope** | Vague | Partial | Single clear task |
+
+**Quick assessment:**
+- 0-3: Needs significant work
+- 4-5: Needs some improvements
+- 6-8: Good, minor tweaks
+
+---
+
+## Fallback: If Still Too Vague
+
+If user chose "Transform directly" but the prompt lacks enough context, ask one natural question:
+
+> "What would Claude need to know to do this well?"
+
+Don't interrogate — one question is enough. Transform with what you learn.
+
+---
+
+## Common Anti-Patterns to Fix
+
+| Anti-Pattern | Problem | Fix |
+|--------------|---------|-----|
+| "fix the bug" | No symptom, no location | Add what users report + where to look |
+| "add tests" | No scope, no cases | Specify edge cases + test patterns |
+| "make it better" | No criteria for "better" | Define specific improvements |
+| "implement X" | No verification | Add test cases or success criteria |
+| "update the code" | No constraints | Add what to preserve, what to avoid |
+
+---
+
+## Success Criteria — Prompt Quality Eval
+
+A well-transformed prompt passes these checks:
+
+### Principle 1: Verification ✅
+| Check | Pass | Fail |
+|-------|------|------|
+| Has success criteria | "run tests", "screenshot matches" | Nothing |
+| Measurable outcome | "response < 500ms" | "make it faster" |
+| Self-verifiable | Claude can check its own work | Requires human judgment |
+| Root cause enforced | "don't suppress error" | Silent about approach |
+
+### Principle 2: Specificity ✅
+| Check | Pass | Fail |
+|-------|------|------|
+| File locations | `src/auth/login.ts` | "the auth code" |
+| Function/class names | `processPayment()` | "that function" |
+| Line numbers (if relevant) | `:42` | "somewhere in there" |
+| CLAUDE.md respected | "check project conventions" | Ignores project rules |
+
+### Principle 3: Constraints ✅
+| Check | Pass | Fail |
+|-------|------|------|
+| What NOT to do | "avoid mocks", "no new deps" | Open-ended |
+| Scope boundaries | "only touch auth module" | Unlimited scope |
+| Pattern to follow | "match UserService.ts style" | No reference |
+
+### Principle 4: Structure ✅
+| Check | Pass | Fail |
+|-------|------|------|
+| Single task | One clear objective | Multiple goals |
+| Phased (if complex) | "explore → plan → implement" | Jump straight to code |
+| Appropriate depth | Matches task complexity | Over/under-specified |
+
+### Principle 5: Rich Content ✅
+| Check | Pass | Fail |
+|-------|------|------|
+| Actual errors | Pasted error message | "it's broken" |
+| Screenshots (UI) | Image attached | "the button looks wrong" |
+| File references | `@filename` or path | "that file" |
+
+### Overall Quality Score
+
+| Score | Meaning | Principles Passed |
+|-------|---------|-------------------|
+| ⭐⭐⭐⭐⭐ | Excellent | All 5 |
+| ⭐⭐⭐⭐ | Good | 4 of 5 |
+| ⭐⭐⭐ | Acceptable | 3 of 5 |
+| ⭐⭐ | Needs work | 2 of 5 |
+| ⭐ | Poor | 1 or 0 |
+
+**Target:** Every transformed prompt should score ⭐⭐⭐⭐ or ⭐⭐⭐⭐⭐
+
+---
+
+## Reference Files
+
+For more examples and patterns:
+
+- **50+ Examples**: See [references/before-after-examples.md](references/before-after-examples.md)
+- **Prompt Templates**: See [references/prompt-patterns.md](references/prompt-patterns.md)
+- **Task Workflows**: See [references/common-workflows.md](references/common-workflows.md)
+- **What to Avoid**: See [references/anti-patterns.md](references/anti-patterns.md)
+- **Official Guide**: See [references/best-practices-guide.md](references/best-practices-guide.md)
+
+---
+
+## Sources
+
+- [Best Practices for Claude Code](https://code.claude.com/docs/en/best-practices) — Official documentation
+- [Claude Code Skills](https://code.claude.com/docs/en/skills) — Skill authoring guide
+- [Anthropic Prompt Engineering](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering) — General prompting patterns
+- [Dicklesworthstone meta_skill](https://github.com/Dicklesworthstone/meta_skill) — "THE EXACT PROMPT" pattern

package/merged-commands/better-auth.md

@@ -0,0 +1,204 @@
+---
+name: better-auth
+description: Implement authentication and authorization with Better Auth - a framework-agnostic TypeScript authentication framework. Features include email/password authentication with verification, OAuth providers (Google, GitHub, Discord, etc.), two-factor authentication (TOTP, SMS), passkeys/WebAuthn support, session management, role-based access control (RBAC), rate limiting, and database adapters. Use when adding authentication to applications, implementing OAuth flows, setting up 2FA/MFA, managing user sessions, configuring authorization rules, or building secure authentication systems for web applications.
+license: MIT
+version: 2.0.0
+---
+
+# Better Auth Skill
+
+Better Auth is comprehensive, framework-agnostic authentication/authorization framework for TypeScript with built-in email/password, social OAuth, and powerful plugin ecosystem for advanced features.
+
+## When to Use
+
+- Implementing auth in TypeScript/JavaScript applications
+- Adding email/password or social OAuth authentication
+- Setting up 2FA, passkeys, magic links, advanced auth features
+- Building multi-tenant apps with organization support
+- Managing sessions and user lifecycle
+- Working with any framework (Next.js, Nuxt, SvelteKit, Remix, Astro, Hono, Express, etc.)
+
+## Quick Start
+
+### Installation
+
+```bash
+npm install better-auth
+# or pnpm/yarn/bun add better-auth
+```
+
+### Environment Setup
+
+Create `.env`:
+```env
+BETTER_AUTH_SECRET=<generated-secret-32-chars-min>
+BETTER_AUTH_URL=http://localhost:3000
+```
+
+### Basic Server Setup
+
+Create `auth.ts` (root, lib/, utils/, or under src/app/server/):
+
+```ts
+import { betterAuth } from "better-auth";
+
+export const auth = betterAuth({
+  database: {
+    // See references/database-integration.md
+  },
+  emailAndPassword: {
+    enabled: true,
+    autoSignIn: true
+  },
+  socialProviders: {
+    github: {
+      clientId: process.env.GITHUB_CLIENT_ID!,
+      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+    }
+  }
+});
+```
+
+### Database Schema
+
+```bash
+npx @better-auth/cli generate  # Generate schema/migrations
+npx @better-auth/cli migrate   # Apply migrations (Kysely only)
+```
+
+### Mount API Handler
+
+**Next.js App Router:**
+```ts
+// app/api/auth/[...all]/route.ts
+import { auth } from "@/lib/auth";
+import { toNextJsHandler } from "better-auth/next-js";
+
+export const { POST, GET } = toNextJsHandler(auth);
+```
+
+**Other frameworks:** See references/email-password-auth.md#framework-setup
+
+### Client Setup
+
+Create `auth-client.ts`:
+
+```ts
+import { createAuthClient } from "better-auth/client";
+
+export const authClient = createAuthClient({
+  baseURL: process.env.NEXT_PUBLIC_BETTER_AUTH_URL || "http://localhost:3000"
+});
+```
+
+### Basic Usage
+
+```ts
+// Sign up
+await authClient.signUp.email({
+  email: "user@example.com",
+  password: "secure123",
+  name: "John Doe"
+});
+
+// Sign in
+await authClient.signIn.email({
+  email: "user@example.com",
+  password: "secure123"
+});
+
+// OAuth
+await authClient.signIn.social({ provider: "github" });
+
+// Session
+const { data: session } = authClient.useSession(); // React/Vue/Svelte
+const { data: session } = await authClient.getSession(); // Vanilla JS
+```
+
+## Feature Selection Matrix
+
+| Feature | Plugin Required | Use Case | Reference |
+|---------|----------------|----------|-----------|
+| Email/Password | No (built-in) | Basic auth | [email-password-auth.md](./references/email-password-auth.md) |
+| OAuth (GitHub, Google, etc.) | No (built-in) | Social login | [oauth-providers.md](./references/oauth-providers.md) |
+| Email Verification | No (built-in) | Verify email addresses | [email-password-auth.md](./references/email-password-auth.md#email-verification) |
+| Password Reset | No (built-in) | Forgot password flow | [email-password-auth.md](./references/email-password-auth.md#password-reset) |
+| Two-Factor Auth (2FA/TOTP) | Yes (`twoFactor`) | Enhanced security | [advanced-features.md](./references/advanced-features.md#two-factor-authentication) |
+| Passkeys/WebAuthn | Yes (`passkey`) | Passwordless auth | [advanced-features.md](./references/advanced-features.md#passkeys-webauthn) |
+| Magic Link | Yes (`magicLink`) | Email-based login | [advanced-features.md](./references/advanced-features.md#magic-link) |
+| Username Auth | Yes (`username`) | Username login | [email-password-auth.md](./references/email-password-auth.md#username-authentication) |
+| Organizations/Multi-tenant | Yes (`organization`) | Team/org features | [advanced-features.md](./references/advanced-features.md#organizations) |
+| Rate Limiting | No (built-in) | Prevent abuse | [advanced-features.md](./references/advanced-features.md#rate-limiting) |
+| Session Management | No (built-in) | User sessions | [advanced-features.md](./references/advanced-features.md#session-management) |
+
+## Auth Method Selection Guide
+
+**Choose Email/Password when:**
+- Building standard web app with traditional auth
+- Need full control over user credentials
+- Targeting users who prefer email-based accounts
+
+**Choose OAuth when:**
+- Want quick signup with minimal friction
+- Users already have social accounts
+- Need access to social profile data
+
+**Choose Passkeys when:**
+- Want passwordless experience
+- Targeting modern browsers/devices
+- Security is top priority
+
+**Choose Magic Link when:**
+- Want passwordless without WebAuthn complexity
+- Targeting email-first users
+- Need temporary access links
+
+**Combine Multiple Methods when:**
+- Want flexibility for different user preferences
+- Building enterprise apps with various auth requirements
+- Need progressive enhancement (start simple, add more options)
+
+## Core Architecture
+
+Better Auth uses client-server architecture:
+1. **Server** (`better-auth`): Handles auth logic, database ops, API routes
+2. **Client** (`better-auth/client`): Provides hooks/methods for frontend
+3. **Plugins**: Extend both server/client functionality
+
+## Implementation Checklist
+
+- [ ] Install `better-auth` package
+- [ ] Set environment variables (SECRET, URL)
+- [ ] Create auth server instance with database config
+- [ ] Run schema migration (`npx @better-auth/cli generate`)
+- [ ] Mount API handler in framework
+- [ ] Create client instance
+- [ ] Implement sign-up/sign-in UI
+- [ ] Add session management to components
+- [ ] Set up protected routes/middleware
+- [ ] Add plugins as needed (regenerate schema after)
+- [ ] Test complete auth flow
+- [ ] Configure email sending (verification/reset)
+- [ ] Enable rate limiting for production
+- [ ] Set up error handling
+
+## Reference Documentation
+
+### Core Authentication
+- [Email/Password Authentication](./references/email-password-auth.md) - Email/password setup, verification, password reset, username auth
+- [OAuth Providers](./references/oauth-providers.md) - Social login setup, provider configuration, token management
+- [Database Integration](./references/database-integration.md) - Database adapters, schema setup, migrations
+
+### Advanced Features
+- [Advanced Features](./references/advanced-features.md) - 2FA/MFA, passkeys, magic links, organizations, rate limiting, session management
+
+## Scripts
+
+- `scripts/better_auth_init.py` - Initialize Better Auth configuration with interactive setup
+
+## Resources
+
+- Docs: https://www.better-auth.com/docs
+- GitHub: https://github.com/better-auth/better-auth
+- Plugins: https://www.better-auth.com/docs/plugins
+- Examples: https://www.better-auth.com/docs/examples