@smicolon/ai-kit 0.0.1 → 0.1.1

package/packs/better-auth/skills/better-auth-patterns/SKILL.md

@@ -0,0 +1,455 @@
+---
+name: Better Auth Patterns
+description: >-
+  Auto-enforce Better Auth implementation patterns. Activates when setting up
+  authentication, configuring providers, creating auth forms, or implementing
+  session management in React applications.
+version: 1.0.0
+---
+
+# Better Auth Patterns
+
+This skill enforces Better Auth best practices for authentication in React applications.
+
+## Server Configuration
+
+### Basic Setup
+```typescript
+// lib/auth.ts
+import { betterAuth } from 'better-auth'
+import { prismaAdapter } from 'better-auth/adapters/prisma'
+import { prisma } from './prisma'
+
+export const auth = betterAuth({
+  database: prismaAdapter(prisma, {
+    provider: 'postgresql',
+  }),
+
+  emailAndPassword: {
+    enabled: true,
+    requireEmailVerification: true,
+  },
+
+  session: {
+    expiresIn: 60 * 60 * 24 * 7, // 7 days
+    updateAge: 60 * 60 * 24,     // Extend daily
+  },
+})
+
+export type Auth = typeof auth
+```
+
+### Social Providers
+```typescript
+import { betterAuth } from 'better-auth'
+
+export const auth = betterAuth({
+  // ... database config
+
+  socialProviders: {
+    google: {
+      clientId: process.env.GOOGLE_CLIENT_ID!,
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+      scopes: ['email', 'profile'],
+    },
+    github: {
+      clientId: process.env.GITHUB_CLIENT_ID!,
+      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+      scopes: ['user:email'],
+    },
+    discord: {
+      clientId: process.env.DISCORD_CLIENT_ID!,
+      clientSecret: process.env.DISCORD_CLIENT_SECRET!,
+    },
+  },
+})
+```
+
+### Two-Factor Authentication
+```typescript
+import { twoFactor } from 'better-auth/plugins/two-factor'
+
+export const auth = betterAuth({
+  // ... base config
+
+  plugins: [
+    twoFactor({
+      issuer: 'MyApp',
+      totpWindow: 1,
+      backupCodes: {
+        enabled: true,
+        count: 10,
+      },
+    }),
+  ],
+})
+```
+
+### Passkeys (WebAuthn)
+```typescript
+import { passkey } from 'better-auth/plugins/passkey'
+
+export const auth = betterAuth({
+  // ... base config
+
+  plugins: [
+    passkey({
+      rpId: 'myapp.com',
+      rpName: 'My App',
+      origin: 'https://myapp.com',
+      attestation: 'none',
+      authenticatorSelection: {
+        authenticatorAttachment: 'platform',
+        userVerification: 'preferred',
+        residentKey: 'preferred',
+      },
+    }),
+  ],
+})
+```
+
+## Client Setup
+
+### Create Auth Client
+```typescript
+// auth/client.ts
+import { createAuthClient } from 'better-auth/react'
+import type { Auth } from '@/lib/auth'
+
+export const authClient = createAuthClient<Auth>({
+  baseURL: import.meta.env.VITE_API_URL,
+  // Optional: Custom fetch for headers
+  fetch: async (url, options) => {
+    return fetch(url, {
+      ...options,
+      credentials: 'include',
+    })
+  },
+})
+
+// Export typed methods
+export const {
+  signIn,
+  signUp,
+  signOut,
+  useSession,
+  getSession,
+  resetPassword,
+  verifyEmail,
+  // Social
+  signInWithGoogle,
+  signInWithGithub,
+  // 2FA
+  enable2FA,
+  disable2FA,
+  verify2FA,
+  // Passkeys
+  registerPasskey,
+  signInWithPasskey,
+} = authClient
+```
+
+### Session Hook
+```typescript
+// auth/hooks.ts
+import { useSession } from './client'
+
+export function useAuth() {
+  const { data: session, isPending, error } = useSession()
+
+  return {
+    user: session?.user ?? null,
+    session: session?.session ?? null,
+    isAuthenticated: !!session?.user,
+    isLoading: isPending,
+    error,
+  }
+}
+
+export function useRequireAuth() {
+  const auth = useAuth()
+  const navigate = useNavigate()
+
+  useEffect(() => {
+    if (!auth.isLoading && !auth.isAuthenticated) {
+      navigate({ to: '/login' })
+    }
+  }, [auth.isLoading, auth.isAuthenticated])
+
+  return auth
+}
+```
+
+## Auth Components
+
+### Login Form
+```typescript
+import { useForm } from '@tanstack/react-form'
+import { zodValidator } from '@tanstack/zod-form-adapter'
+import { signIn } from '@/auth/client'
+import { z } from 'zod'
+
+const loginSchema = z.object({
+  email: z.string().email(),
+  password: z.string().min(1, 'Password is required'),
+})
+
+export function LoginForm() {
+  const [error, setError] = useState<string | null>(null)
+  const navigate = useNavigate()
+
+  const form = useForm({
+    defaultValues: { email: '', password: '' },
+    validatorAdapter: zodValidator(),
+    validators: { onChange: loginSchema },
+    onSubmit: async ({ value }) => {
+      setError(null)
+      const result = await signIn.email(value)
+
+      if (result.error) {
+        setError(result.error.message)
+        return
+      }
+
+      navigate({ to: '/dashboard' })
+    },
+  })
+
+  return (
+    <form onSubmit={(e) => { e.preventDefault(); form.handleSubmit() }}>
+      {error && <div className="error">{error}</div>}
+
+      <form.Field
+        name="email"
+        children={(field) => (/* email input */)}
+      />
+
+      <form.Field
+        name="password"
+        children={(field) => (/* password input */)}
+      />
+
+      <form.Subscribe
+        selector={(state) => state.isSubmitting}
+        children={(isSubmitting) => (
+          <button type="submit" disabled={isSubmitting}>
+            {isSubmitting ? 'Signing in...' : 'Sign In'}
+          </button>
+        )}
+      />
+    </form>
+  )
+}
+```
+
+### Social Login Buttons
+```typescript
+import { signInWithGoogle, signInWithGithub } from '@/auth/client'
+
+export function SocialLoginButtons() {
+  const handleGoogleLogin = async () => {
+    await signInWithGoogle({
+      callbackURL: '/dashboard',
+    })
+  }
+
+  const handleGithubLogin = async () => {
+    await signInWithGithub({
+      callbackURL: '/dashboard',
+    })
+  }
+
+  return (
+    <div className="flex flex-col gap-2">
+      <button onClick={handleGoogleLogin} className="btn-social">
+        <GoogleIcon /> Continue with Google
+      </button>
+      <button onClick={handleGithubLogin} className="btn-social">
+        <GithubIcon /> Continue with GitHub
+      </button>
+    </div>
+  )
+}
+```
+
+### 2FA Setup
+```typescript
+import { enable2FA, verify2FA } from '@/auth/client'
+import { useState } from 'react'
+
+export function TwoFactorSetup() {
+  const [qrCode, setQrCode] = useState<string | null>(null)
+  const [secret, setSecret] = useState<string | null>(null)
+  const [code, setCode] = useState('')
+  const [backupCodes, setBackupCodes] = useState<string[]>([])
+
+  const handleEnable = async () => {
+    const result = await enable2FA()
+    if (result.data) {
+      setQrCode(result.data.qrCode)
+      setSecret(result.data.secret)
+    }
+  }
+
+  const handleVerify = async () => {
+    const result = await verify2FA({ code })
+    if (result.data) {
+      setBackupCodes(result.data.backupCodes)
+    }
+  }
+
+  if (backupCodes.length > 0) {
+    return (
+      <div>
+        <h3>Save your backup codes</h3>
+        <ul>
+          {backupCodes.map((code, i) => (
+            <li key={i}>{code}</li>
+          ))}
+        </ul>
+      </div>
+    )
+  }
+
+  if (qrCode) {
+    return (
+      <div>
+        <img src={qrCode} alt="2FA QR Code" />
+        <p>Secret: {secret}</p>
+        <input
+          value={code}
+          onChange={(e) => setCode(e.target.value)}
+          placeholder="Enter 6-digit code"
+        />
+        <button onClick={handleVerify}>Verify</button>
+      </div>
+    )
+  }
+
+  return (
+    <button onClick={handleEnable}>Enable 2FA</button>
+  )
+}
+```
+
+### Passkey Registration
+```typescript
+import { registerPasskey, signInWithPasskey } from '@/auth/client'
+
+export function PasskeyManager() {
+  const [error, setError] = useState<string | null>(null)
+
+  const handleRegister = async () => {
+    setError(null)
+    const result = await registerPasskey({
+      name: 'My Device',
+    })
+
+    if (result.error) {
+      setError(result.error.message)
+    }
+  }
+
+  const handleSignIn = async () => {
+    setError(null)
+    const result = await signInWithPasskey()
+
+    if (result.error) {
+      setError(result.error.message)
+    }
+  }
+
+  return (
+    <div>
+      {error && <div className="error">{error}</div>}
+      <button onClick={handleRegister}>Register Passkey</button>
+      <button onClick={handleSignIn}>Sign in with Passkey</button>
+    </div>
+  )
+}
+```
+
+## Router Integration
+
+### Root Route with Session
+```typescript
+// routes/__root.tsx
+import { createRootRouteWithContext } from '@tanstack/react-router'
+import { getSession } from '@/auth/client'
+
+export const Route = createRootRouteWithContext<RouterContext>()({
+  beforeLoad: async () => {
+    const session = await getSession()
+    return { session: session?.data ?? null }
+  },
+})
+```
+
+### Protected Route Layout
+```typescript
+// routes/_auth.tsx
+import { createFileRoute, redirect } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/_auth')({
+  beforeLoad: async ({ context, location }) => {
+    if (!context.session) {
+      throw redirect({
+        to: '/login',
+        search: { redirect: location.pathname },
+      })
+    }
+  },
+})
+```
+
+### Guest-Only Routes
+```typescript
+// routes/_guest.tsx
+import { createFileRoute, redirect } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/_guest')({
+  beforeLoad: async ({ context }) => {
+    if (context.session) {
+      throw redirect({ to: '/dashboard' })
+    }
+  },
+})
+```
+
+## Conventions
+
+1. **Server config in lib/** - Keep auth config at `lib/auth.ts`
+2. **Client in auth/** - Export typed client from `auth/client.ts`
+3. **Route protection** - Use pathless layouts (`_auth.tsx`)
+4. **Session in context** - Load session in `__root.tsx`
+5. **Error handling** - Always check `result.error`
+6. **Type safety** - Use `Auth` type from server config
+
+## Anti-Patterns
+
+```typescript
+// ❌ WRONG: Untyped client
+const authClient = createAuthClient({})
+
+// ✅ CORRECT: Typed client
+const authClient = createAuthClient<Auth>({})
+
+// ❌ WRONG: No error handling
+const result = await signIn.email(data)
+navigate('/dashboard')
+
+// ✅ CORRECT: Check for errors
+const result = await signIn.email(data)
+if (result.error) {
+  setError(result.error.message)
+  return
+}
+navigate('/dashboard')
+
+// ❌ WRONG: Client-side session check only
+if (localStorage.getItem('session')) { ... }
+
+// ✅ CORRECT: Server-validated session
+const { data: session } = useSession()
+if (session) { ... }
+```

package/packs/dev-loop/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "dev-loop",
+  "description": "Autonomous development loops for iterative coding with automatic continuation",
+  "version": "1.0.0",
+  "author": {
+    "name": "Smicolon",
+    "email": "dev@smicolon.com",
+    "url": "https://github.com/smicolon"
+  }
+}

package/packs/dev-loop/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+All notable changes to the smi-dev-loop plugin will be documented in this file.
+
+## [Unreleased]
+
+### Changed
+- Renamed from `smi-dev-loop` to `dev-loop` as part of ai-kit migration
+- Moved from `plugins/smi-dev-loop/` to `packs/dev-loop/`
+
+## [1.2.1] - 2026-01-02
+
+### Fixed
+- Rewrite stop hook based on official Ralph Wiggum pattern
+- Fix infinite loop bug when agent responds with natural language completion
+- Add comprehensive error handling with clear user messages
+- Use `systemMessage` field for iteration status
+- Add anti-gaming instruction ("do not lie to exit!")
+- Atomic file updates with PID suffix
+
+### Changed
+- Setup script now matches Ralph Wiggum quality with better argument parsing
+- Multi-word prompts work without quotes
+- Added `-h|--help` with full documentation
+- Defaults remain: 50 iterations, "DONE" promise
+
+## [1.2.0] - 2026-01-02
+
+### Added
+- Quality checklist enforcement for plan generation
+- Required file tables: "Files to Modify" and "New Files to Create"
+- Code snippets in implementation phases
+- Acceptance criteria section with Given/When/Then format
+- Framework-specific stuck handling (not generic)
+- `references/good-example.md` - High-quality Flutter migration example
+- Anti-patterns documentation to avoid vague plans
+- **17+ framework auto-detection**: Flutter, React Native, Django, FastAPI, Flask, NestJS, Next.js, Nuxt.js, Hono, Express, TanStack, Go, Rust, Rails, Laravel
+- **Custom framework support**: `--test-cmd` and `--lint-cmd` flags for any stack
+- Test patterns for Go, Rust, Rails, Laravel, FastAPI, Hono, Flutter
+
+### Changed
+- Enhanced `dev-plan.md` command with deep codebase analysis step
+- Improved `plan-template.md` with all required sections
+- Updated `SKILL.md` with specificity requirements
+- Tasks now require file paths and implementation details
+- Framework detection now works with any tech stack
+- **Package manager auto-detection**: bun (default) > pnpm > yarn > npm based on lockfile
+
+### Fixed
+- Plans now consistently include measurable success criteria
+- Self-correction rules are phase-specific instead of generic
+
+## [1.1.0] - 2025-01-02
+
+### Added
+- `/dev-plan` command for TDD planning phase
+- `tdd-planner` skill for structured development plans
+
+### Fixed
+- Stop hook transcript parsing
+- Progress tracking improvements
+
+## [1.0.0] - 2024-12-15
+
+### Added
+- Initial stable release
+- 3 commands: dev-loop, dev-plan, cancel-dev
+- Autonomous development loop with Red-Green-Refactor
+- Stop hook for continuation logic

package/packs/dev-loop/README.md

@@ -0,0 +1,155 @@
+# dev-loop
+
+Autonomous TDD development loops with planning phase and iterative coding.
+
+## Overview
+
+This plugin provides a "dev loop" mechanism that keeps Claude working on a task until completion. Based on the Ralph Wiggum pattern, it uses a Stop hook to intercept Claude's exit and re-feed the original prompt.
+
+**New in v1.1**: Planning phase with `/dev-plan` for structured TDD workflows.
+
+## Installation
+
+```bash
+/plugin install dev-loop
+```
+
+## Recommended Workflow
+
+For best results, use the planning phase first:
+
+```bash
+# 1. Generate structured TDD plan
+/dev-plan "Build user authentication with JWT"
+
+# 2. Review and edit .claude/dev-plan.local.md if needed
+
+# 3. Execute with structured plan
+/dev-loop --from-plan
+```
+
+## Commands
+
+### /dev-plan
+
+Generate a structured TDD plan for dev-loop execution:
+
+```bash
+# Basic usage - auto-detects framework
+/dev-plan "Build user authentication with JWT"
+
+# With explicit framework
+/dev-plan "Build API endpoints" --framework django
+
+# With interactive questions
+/dev-plan "Implement payment system" --interactive
+```
+
+Creates `.claude/dev-plan.local.md` with:
+- TDD phases (Red-Green-Refactor)
+- Clear verification commands
+- Self-correction rules
+- Stuck handling
+
+### /dev-loop
+
+Start a development loop:
+
+```bash
+# Recommended: Use with plan
+/dev-loop --from-plan
+
+# Simple usage - just provide your prompt
+/dev-loop "Build a user authentication system with login and logout"
+
+# With custom max iterations (default: 50)
+/dev-loop "Refactor the database layer" --max-iterations 30
+
+# With custom completion promise (default: DONE)
+/dev-loop "Fix all TypeScript errors" --promise "ALL_FIXED"
+```
+
+### /cancel-dev
+
+Cancel an active loop:
+
+```bash
+/cancel-dev
+```
+
+## How It Works
+
+1. **Start**: `/dev-loop "Your prompt"` creates a state file at `.claude/dev-loop.local.md`
+2. **Work**: Claude works on your task iteratively
+3. **Continue**: When Claude tries to stop, the Stop hook checks if `<promise>DONE</promise>` was output
+4. **Complete**: If the promise is found, the loop ends. Otherwise, the prompt is re-fed.
+5. **Safety**: After 50 iterations (configurable), the loop stops automatically.
+
+## State File
+
+The loop state is stored in `.claude/dev-loop.local.md`:
+
+```yaml
+---
+active: true
+iteration: 1
+max_iterations: 50
+completion_promise: "DONE"
+started_at: "2026-01-01T00:00:00Z"
+---
+
+Your prompt text here
+```
+
+## Completion
+
+To end the loop, output the completion promise:
+
+```
+<promise>DONE</promise>
+```
+
+Or with a custom promise:
+
+```
+<promise>YOUR_CUSTOM_PROMISE</promise>
+```
+
+## Use Cases
+
+- **TDD Development**: Use `/dev-plan` for structured Red-Green-Refactor phases
+- **Bug Fixing**: Keep working until the bug is resolved
+- **Refactoring**: Iteratively improve code structure
+- **Feature Building**: Build complex features step by step with planning
+- **Code Review Fixes**: Address all review comments
+
+## TDD Planner Skill
+
+The `tdd-planner` skill auto-activates when you ask to:
+- "Plan a feature"
+- "Prepare for dev loop"
+- "Break down this task"
+- "Structure TDD approach"
+
+It generates structured prompts with:
+- Clear success criteria
+- TDD phases (Red → Green → Refactor)
+- Verification commands
+- Self-correction rules
+
+## Combining with Framework Plugins
+
+```bash
+# Install loop + Django conventions
+/plugin install dev-loop django
+
+# Now use both
+/dev-loop "Build a REST API for user management following Django conventions"
+```
+
+## Technical Details
+
+- **Hook Type**: Stop hook with bash command
+- **State File**: `.claude/dev-loop.local.md` (gitignored)
+- **Default Iterations**: 50
+- **Default Promise**: "DONE"

package/packs/dev-loop/commands/cancel-dev.md

@@ -0,0 +1,21 @@
+---
+name: cancel-dev
+description: "Cancel active dev loop"
+---
+
+```!
+if [ -f ".claude/dev-loop.local.md" ]; then
+  rm ".claude/dev-loop.local.md"
+  echo "Dev loop cancelled."
+else
+  echo "No active dev loop to cancel."
+fi
+```
+
+# Dev Loop Cancelled
+
+The dev loop has been cancelled. You can start a new loop with:
+
+```bash
+/dev-loop "Your prompt here"
+```