create-agentic-app 1.1.58 → 1.1.60

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agentic-app",
-  "version": "1.1.58",
+  "version": "1.1.60",
   "description": "Scaffold a new agentic AI application with Next.js, Better Auth, and AI SDK",
   "type": "module",
   "bin": {

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

@@ -10,7 +10,7 @@ description: >
 
 # Checkpoint Commit
 
-Create a comprehensive checkpoint commit that captures all current changes with a detailed, well-structured commit message.
+Create a checkpoint commit that captures all current changes — but only after the code passes lint, type check, and build.
 
 ## Instructions
 
@@ -23,7 +23,17 @@ Run these commands to understand the full picture:
 3. `git diff --cached` — see already-staged changes
 4. `git log -5 --oneline` — understand this repo's commit message style
 
-### Step 2: Stage Everything
+### 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:
 
@@ -31,20 +41,16 @@ Stage all changes — tracked modifications, deletions, and new untracked files:
 git add -A
 ```
 
-### Step 3: Craft the Commit Message
+### 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): detailed description including:
-  - What changes were made (key modifications)
-  - Why these changes were made (purpose/motivation)
-  - Important technical details or decisions
-  - Breaking changes or migration notes if applicable
+- **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 4: Commit
+### Step 5: Commit
 
 Create the commit using a heredoc for proper formatting:
 
@@ -52,14 +58,14 @@ Create the commit using a heredoc for proper formatting:
 git commit -m "$(cat <<'EOF'
 {first line}
 
-{body}
+{tldr}
 
 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 EOF
 )"
 ```
 
-### Step 5: Report
+### Step 6: Report
 
 Display:
 - The commit hash and message summary
@@ -70,6 +76,7 @@ Display:
 
 - 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
-- Make the commit message descriptive enough that someone reading `git log` understands what was accomplished
+- 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/ship-it/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: ship-it
+description: >
+  Push the current branch to GitHub and create a pull request. Use this skill when the user says
+  "ship it", "ship this", "push to github", "create a pr", "open a pull request", "send for review",
+  "get this reviewed", or wants to push their work and open a PR. Also use when the user says
+  "/ship-it". This skill handles prerequisites, branching, pushing, and PR creation — it does not
+  commit or run quality checks (use checkpoint for that first).
+---
+
+# Ship It
+
+Push your work to GitHub and open a pull request — handling prerequisites, branch creation, pushing, and PR generation automatically.
+
+This skill complements `checkpoint`. Use `checkpoint` to commit locally (with quality gates), then `ship-it` to get the code to GitHub for review.
+
+## Instructions
+
+### Step 0: Prerequisites
+
+Verify tooling before doing anything else.
+
+1. **GitHub CLI installed?**
+   ```bash
+   gh --version
+   ```
+   If the command fails (not found):
+   - Detect the platform and attempt to install:
+     - **Windows:** `winget install --id GitHub.cli`
+     - **macOS:** `brew install gh`
+     - **Linux (Debian/Ubuntu):** follow the official apt instructions
+   - If auto-install fails, tell the user what to install and stop.
+
+2. **GitHub CLI authenticated?**
+   ```bash
+   gh auth status
+   ```
+   If not authenticated, tell the user:
+   ```
+   GitHub CLI is not logged in. Please run this in the prompt:
+     ! gh auth login
+   Then re-run /ship-it.
+   ```
+   Stop here — do not proceed until auth is confirmed.
+
+3. **Git remote exists?**
+   ```bash
+   git remote -v
+   ```
+   If no remote named `origin` exists, stop and tell the user:
+   ```
+   No git remote found. Add one with:
+     git remote add origin https://github.com/{user}/{repo}.git
+   ```
+
+### Step 1: Detect the Environment
+
+Run these commands to understand the current state:
+
+1. `git branch --show-current` — get the current branch name
+2. Detect the default branch:
+   ```bash
+   gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'
+   ```
+3. `git status --porcelain` — check for uncommitted changes
+
+If there are uncommitted changes, stop and tell the user:
+```
+You have uncommitted changes. Run /checkpoint first to commit them, then /ship-it to push.
+```
+
+Store the default branch name for use throughout the remaining steps.
+
+### Step 2: Check for Unpushed Commits
+
+Determine if there are commits that haven't been pushed yet.
+
+**If on a feature branch with a remote tracking branch:**
+```bash
+git log @{upstream}..HEAD --oneline
+```
+
+**If on a feature branch with no remote tracking branch, or on the default branch:**
+```bash
+git log origin/{default_branch}..HEAD --oneline
+```
+
+If there are **no unpushed commits**, stop and tell the user:
+```
+Nothing to ship — all commits are already pushed.
+```
+
+Save the list of unpushed commit messages for use in later steps.
+
+### Step 3: Handle Branching
+
+**If already on a feature branch** (not the default branch):
+- Stay on it. No branching needed.
+- Skip to Step 4.
+
+**If on the default branch:**
+- Generate a branch name from the unpushed commit messages:
+  - Read the commit subjects
+  - Derive a kebab-case branch name with a conventional prefix: `feat/`, `fix/`, `refactor/`, `chore/`, `docs/` based on the commit content
+  - Keep it short (3-5 words max after the prefix), e.g., `feat/add-user-auth`, `fix/login-redirect-loop`
+  - Strip special characters, lowercase everything
+- Create and switch to the new branch:
+  ```bash
+  git checkout -b {branch_name}
+  ```
+- Tell the user: `Created branch {branch_name}`
+
+### Step 4: Push to Origin
+
+```bash
+git push -u origin {branch_name}
+```
+
+If the branch already has a remote tracking branch, a regular `git push` is fine.
+
+### Step 5: Check for Existing PR
+
+Before creating a new PR, check if one already exists for this branch:
+
+```bash
+gh pr view --json number,url,title,state 2>/dev/null
+```
+
+If a PR already exists and is **open**:
+- Do NOT create a new one
+- Skip to Step 7 and report the existing PR with a note that new commits were pushed.
+
+If no PR exists (or it is closed/merged), proceed to Step 6.
+
+### Step 6: Create the Pull Request
+
+Generate the PR title and body from the unpushed commits:
+
+- **Title**: concise summary under 70 chars. If single commit, use its subject. If multiple, synthesize a short summary. Imperative mood.
+- **Body**: TL;DR of the changes in 2-4 bullet points max.
+
+```bash
+gh pr create --base {default_branch} --head {branch_name} --title "{title}" --body "$(cat <<'EOF'
+## Summary
+{2-4 bullet points}
+
+---
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+EOF
+)"
+```
+
+### Step 7: Report
+
+Display the result clearly:
+
+```
+Shipped to GitHub:
+  Branch: {branch_name}
+  PR: #{number} — {title}
+  URL: {url}
+```
+
+## Important
+
+- Do NOT run lint, type-check, or build — that is checkpoint's job
+- Do NOT commit anything — only push existing commits and create a PR
+- If the user has uncommitted changes, tell them to run /checkpoint first
+- Keep the PR body short — a TL;DR, not an essay
+- Always check for an existing open PR before creating a new one to avoid duplicates
+- Detect the default branch dynamically — do not hardcode `main` or `master`
+- When creating a branch from the default branch, use conventional prefixes (`feat/`, `fix/`, etc.) with kebab-case names
+- Never run destructive git operations (no `--force`, no `reset --hard`)
+- If `gh` is not installed or authenticated, help the user get set up before proceeding

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

@@ -10,7 +10,7 @@ description: >
 
 # Checkpoint Commit
 
-Create a comprehensive checkpoint commit that captures all current changes with a detailed, well-structured commit message.
+Create a checkpoint commit that captures all current changes — but only after the code passes lint, type check, and build.
 
 ## Instructions
 
@@ -23,7 +23,17 @@ Run these commands to understand the full picture:
 3. `git diff --cached` — see already-staged changes
 4. `git log -5 --oneline` — understand this repo's commit message style
 
-### Step 2: Stage Everything
+### 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:
 
@@ -31,20 +41,16 @@ Stage all changes — tracked modifications, deletions, and new untracked files:
 git add -A
 ```
 
-### Step 3: Craft the Commit Message
+### 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): detailed description including:
-  - What changes were made (key modifications)
-  - Why these changes were made (purpose/motivation)
-  - Important technical details or decisions
-  - Breaking changes or migration notes if applicable
+- **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 4: Commit
+### Step 5: Commit
 
 Create the commit using a heredoc for proper formatting:
 
@@ -52,14 +58,14 @@ Create the commit using a heredoc for proper formatting:
 git commit -m "$(cat <<'EOF'
 {first line}
 
-{body}
+{tldr}
 
 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 EOF
 )"
 ```
 
-### Step 5: Report
+### Step 6: Report
 
 Display:
 - The commit hash and message summary
@@ -70,6 +76,7 @@ Display:
 
 - 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
-- Make the commit message descriptive enough that someone reading `git log` understands what was accomplished
+- 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/.claude/skills/ship-it/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: ship-it
+description: >
+  Push the current branch to GitHub and create a pull request. Use this skill when the user says
+  "ship it", "ship this", "push to github", "create a pr", "open a pull request", "send for review",
+  "get this reviewed", or wants to push their work and open a PR. Also use when the user says
+  "/ship-it". This skill handles prerequisites, branching, pushing, and PR creation — it does not
+  commit or run quality checks (use checkpoint for that first).
+---
+
+# Ship It
+
+Push your work to GitHub and open a pull request — handling prerequisites, branch creation, pushing, and PR generation automatically.
+
+This skill complements `checkpoint`. Use `checkpoint` to commit locally (with quality gates), then `ship-it` to get the code to GitHub for review.
+
+## Instructions
+
+### Step 0: Prerequisites
+
+Verify tooling before doing anything else.
+
+1. **GitHub CLI installed?**
+   ```bash
+   gh --version
+   ```
+   If the command fails (not found):
+   - Detect the platform and attempt to install:
+     - **Windows:** `winget install --id GitHub.cli`
+     - **macOS:** `brew install gh`
+     - **Linux (Debian/Ubuntu):** follow the official apt instructions
+   - If auto-install fails, tell the user what to install and stop.
+
+2. **GitHub CLI authenticated?**
+   ```bash
+   gh auth status
+   ```
+   If not authenticated, tell the user:
+   ```
+   GitHub CLI is not logged in. Please run this in the prompt:
+     ! gh auth login
+   Then re-run /ship-it.
+   ```
+   Stop here — do not proceed until auth is confirmed.
+
+3. **Git remote exists?**
+   ```bash
+   git remote -v
+   ```
+   If no remote named `origin` exists, stop and tell the user:
+   ```
+   No git remote found. Add one with:
+     git remote add origin https://github.com/{user}/{repo}.git
+   ```
+
+### Step 1: Detect the Environment
+
+Run these commands to understand the current state:
+
+1. `git branch --show-current` — get the current branch name
+2. Detect the default branch:
+   ```bash
+   gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'
+   ```
+3. `git status --porcelain` — check for uncommitted changes
+
+If there are uncommitted changes, stop and tell the user:
+```
+You have uncommitted changes. Run /checkpoint first to commit them, then /ship-it to push.
+```
+
+Store the default branch name for use throughout the remaining steps.
+
+### Step 2: Check for Unpushed Commits
+
+Determine if there are commits that haven't been pushed yet.
+
+**If on a feature branch with a remote tracking branch:**
+```bash
+git log @{upstream}..HEAD --oneline
+```
+
+**If on a feature branch with no remote tracking branch, or on the default branch:**
+```bash
+git log origin/{default_branch}..HEAD --oneline
+```
+
+If there are **no unpushed commits**, stop and tell the user:
+```
+Nothing to ship — all commits are already pushed.
+```
+
+Save the list of unpushed commit messages for use in later steps.
+
+### Step 3: Handle Branching
+
+**If already on a feature branch** (not the default branch):
+- Stay on it. No branching needed.
+- Skip to Step 4.
+
+**If on the default branch:**
+- Generate a branch name from the unpushed commit messages:
+  - Read the commit subjects
+  - Derive a kebab-case branch name with a conventional prefix: `feat/`, `fix/`, `refactor/`, `chore/`, `docs/` based on the commit content
+  - Keep it short (3-5 words max after the prefix), e.g., `feat/add-user-auth`, `fix/login-redirect-loop`
+  - Strip special characters, lowercase everything
+- Create and switch to the new branch:
+  ```bash
+  git checkout -b {branch_name}
+  ```
+- Tell the user: `Created branch {branch_name}`
+
+### Step 4: Push to Origin
+
+```bash
+git push -u origin {branch_name}
+```
+
+If the branch already has a remote tracking branch, a regular `git push` is fine.
+
+### Step 5: Check for Existing PR
+
+Before creating a new PR, check if one already exists for this branch:
+
+```bash
+gh pr view --json number,url,title,state 2>/dev/null
+```
+
+If a PR already exists and is **open**:
+- Do NOT create a new one
+- Skip to Step 7 and report the existing PR with a note that new commits were pushed.
+
+If no PR exists (or it is closed/merged), proceed to Step 6.
+
+### Step 6: Create the Pull Request
+
+Generate the PR title and body from the unpushed commits:
+
+- **Title**: concise summary under 70 chars. If single commit, use its subject. If multiple, synthesize a short summary. Imperative mood.
+- **Body**: TL;DR of the changes in 2-4 bullet points max.
+
+```bash
+gh pr create --base {default_branch} --head {branch_name} --title "{title}" --body "$(cat <<'EOF'
+## Summary
+{2-4 bullet points}
+
+---
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+EOF
+)"
+```
+
+### Step 7: Report
+
+Display the result clearly:
+
+```
+Shipped to GitHub:
+  Branch: {branch_name}
+  PR: #{number} — {title}
+  URL: {url}
+```
+
+## Important
+
+- Do NOT run lint, type-check, or build — that is checkpoint's job
+- Do NOT commit anything — only push existing commits and create a PR
+- If the user has uncommitted changes, tell them to run /checkpoint first
+- Keep the PR body short — a TL;DR, not an essay
+- Always check for an existing open PR before creating a new one to avoid duplicates
+- Detect the default branch dynamically — do not hardcode `main` or `master`
+- When creating a branch from the default branch, use conventional prefixes (`feat/`, `fix/`, etc.) with kebab-case names
+- Never run destructive git operations (no `--force`, no `reset --hard`)
+- If `gh` is not installed or authenticated, help the user get set up before proceeding

package/template/AGENTS.md

@@ -17,7 +17,12 @@
 - Identify changes from the plan that can be implemented in parallel, and use sub-agents to implement the features efficiently
 - When using sub-agents to implement features, act as a coordinator only
 - Use the best model for the task - premium models for complex tasks (like coding) and mid-tier models for simpler tasks, like documentation
-- After completing features (large or small), always run commands like lint and type check to check code quality
+- After completing features (large or small), always run commands like lint, type check and next build to check code quality
+
+## DATABASE SCHEMA CHANGES
+
+- Whenever you make changes to the database schema, ALWAYS run the drizzle generate and migrate commands
+- NEVER run drizzle push!
 
 ## TESTING
 
@@ -27,5 +32,5 @@
 
 ## UI DESIGN
 
-- Always following the UI design system when creating or reviewing components or pages.
+- Always follow the UI design system when creating or reviewing components or pages.
 - Design System: @DESIGN.md

package/template/README.md

@@ -1,440 +1,388 @@
-# Agentic Coding Boilerplate
+# Agentic Coding Starter Kit
 
-A complete agentic coding boilerplate with authentication, PostgreSQL database, AI chat functionality, and modern UI components - perfect for building AI-powered applications and autonomous agents.
+A production-oriented starter kit for building AI-powered web apps with an agentic development workflow. It gives you a working Next.js app, authentication, PostgreSQL, Drizzle ORM, AI SDK integration, shadcn/ui components, and project instructions that help coding agents plan, split, implement, review, and verify changes.
 
-## 🚀 Features
+The goal is simple: install the starter, describe the product you want to build, and let your coding agent help turn the boilerplate into your actual POC, MVP, or internal tool.
 
-- **🔐 Authentication**: Better Auth with Google OAuth integration
-- **🗃️ Database**: Drizzle ORM with PostgreSQL
-- **🤖 AI Integration**: Vercel AI SDK with OpenRouter (access to 100+ AI models)
-- **📁 File Storage**: Automatic local/Vercel Blob storage with seamless switching
-- **🎨 UI Components**: shadcn/ui with Tailwind CSS
-- **⚡ Modern Stack**: Next.js 16, React 19, TypeScript
-- **📱 Responsive**: Mobile-first design approach
+## What You Get
 
-## 🎥 Video Tutorial
+- **Next.js 16 and React 19** with the App Router
+- **TypeScript** and a strict project setup
+- **Better Auth** with email/password enabled by default
+- **PostgreSQL and Drizzle ORM** for schema and migrations
+- **AI SDK and OpenRouter** for chat and AI features
+- **shadcn/ui, Tailwind CSS, and Lucide icons** for the UI foundation
+- **Local or Vercel Blob file storage** through one storage abstraction
+- **Agent instructions** through `AGENTS.md` and `CLAUDE.md`
+- **Agent skills** for specs, implementation, reviews, security scans, UI work, and shipping
 
-Watch the complete walkthrough of this agentic coding template:
+## Quick Start
 
-[![Agentic Coding Boilerplate Tutorial](https://img.youtube.com/vi/JQ86N3WOAh4/maxresdefault.jpg)](https://youtu.be/JQ86N3WOAh4)
-
-<a href="https://youtu.be/JQ86N3WOAh4" target="_blank" rel="noopener noreferrer">🔗 Watch on YouTube</a>
-
-## ☕ Support This Project
-
-If this boilerplate helped you build something awesome, consider buying me a coffee!
-
-[![Buy me a coffee](https://img.shields.io/badge/Buy_Me_A_Coffee-FFDD00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black)](https://www.buymeacoffee.com/leonvanzyl)
-
-## 📋 Prerequisites
-
-Before you begin, ensure you have the following installed on your machine:
-
-- **Node.js**: Version 18.0 or higher (<a href="https://nodejs.org/" target="_blank">Download here</a>)
-- **Git**: For cloning the repository (<a href="https://git-scm.com/" target="_blank">Download here</a>)
-- **PostgreSQL**: Either locally installed or access to a hosted service like Vercel Postgres
-
-## 🛠️ Quick Setup
-
-### Automated Setup (Recommended)
-
-Get started with a single command:
+Create a new app with the CLI:
 
 ```bash
 npx create-agentic-app@latest my-app
 cd my-app
 ```
 
-Or create in the current directory:
+Or create the app in the current directory:
 
 ```bash
 npx create-agentic-app@latest .
 ```
 
-The CLI will:
-- Copy all boilerplate files
-- Install dependencies with your preferred package manager (pnpm/npm/yarn)
-- Set up your environment file
-
-**Next steps after running the command:**
-
-1. Update `.env` with your API keys and database credentials
-2. Start the database: `docker compose up -d`
-3. Run migrations: `npm run db:migrate`
-4. Start dev server: `npm run dev`
-
-### Manual Setup (Alternative)
-
-If you prefer to set up manually:
-
-**1. Clone or Download the Repository**
-
-**Option A: Clone with Git**
+Then configure and run the app:
 
 ```bash
-git clone https://github.com/leonvanzyl/agentic-coding-starter-kit.git
-cd agentic-coding-starter-kit
+cp env.example .env
+docker compose up -d
+pnpm db:migrate
+pnpm dev
 ```
 
-**Option B: Download ZIP**
-Download the repository as a ZIP file and extract it to your desired location.
+Open [http://localhost:3000](http://localhost:3000).
 
-**2. Install Dependencies**
+The CLI copies the starter files, installs dependencies with your selected package manager, and prepares the environment file. If you use `npm`, replace the `pnpm` commands above with `npm run`.
 
-```bash
-npm install
-```
-
-**3. Environment Setup**
+## Prerequisites
 
-Copy the example environment file:
+- Node.js 18 or newer
+- Git
+- PostgreSQL, either through the included Docker Compose file or a hosted provider
+- A package manager: `pnpm`, `npm`, or `yarn`
+- Optional: an OpenRouter API key for AI chat features
+- Optional: a Vercel account for deployment, hosted Postgres, and Blob storage
 
-```bash
-cp env.example .env
-```
+## Environment Variables
 
-Fill in your environment variables in the `.env` file:
+Start from `env.example` and update values for your environment:
 
 ```env
 # Database
-POSTGRES_URL="postgresql://username:password@localhost:5432/your_database_name"
+POSTGRES_URL=postgresql://dev_user:dev_password@localhost:5432/postgres_dev
 
 # Authentication - Better Auth
-BETTER_AUTH_SECRET="your-random-32-character-secret-key-here"
+BETTER_AUTH_SECRET=your-random-secret
 
-# Google OAuth (Get from Google Cloud Console)
-GOOGLE_CLIENT_ID="your-google-client-id"
-GOOGLE_CLIENT_SECRET="your-google-client-secret"
-
-# AI Integration via OpenRouter (Optional - for chat functionality)
-# Get your API key from: https://openrouter.ai/settings/keys
-# View available models at: https://openrouter.ai/models
-OPENROUTER_API_KEY="sk-or-v1-your-openrouter-api-key-here"
+# AI Integration via OpenRouter
+OPENROUTER_API_KEY=
 OPENROUTER_MODEL="openai/gpt-5-mini"
 
-# App URL (for production deployments)
+# Optional - for vector search only
+OPENAI_EMBEDDING_MODEL="text-embedding-3-large"
+
+# App URL
 NEXT_PUBLIC_APP_URL="http://localhost:3000"
 
-# File Storage (Optional - for file upload functionality)
-# Leave empty to use local storage (public/uploads/) in development
-# Set to enable Vercel Blob storage in production
-BLOB_READ_WRITE_TOKEN=""
+# File storage
+BLOB_READ_WRITE_TOKEN=
+
+# Polar payment processing
+POLAR_WEBHOOK_SECRET=polar_
+POLAR_ACCESS_TOKEN=polar_
 ```
 
-**4. Database Setup**
+For local development, the default database URL works with the included `docker-compose.yml`. For production, use the database URL from your hosting provider.
 
-Generate and run database migrations:
+Generate a strong `BETTER_AUTH_SECRET` before deploying. The starter ships with a development value only so you can get moving quickly.
 
-```bash
-npm run db:generate
-npm run db:migrate
-```
+## Default Auth
 
-**5. Start the Development Server**
+The starter now defaults to **email and password authentication** through Better Auth. This keeps the first setup small and helps you start building POCs and MVPs without creating OAuth credentials up front.
 
-```bash
-npm run dev
-```
+The current auth setup includes:
 
-Your application will be available at [http://localhost:3000](http://localhost:3000)
+- user registration
+- email/password login
+- protected routes
+- password reset flow
+- email verification flow
 
-## ⚙️ Service Configuration
+In development, verification and password reset links are logged to the terminal instead of being sent through an email provider. When you are ready for production, ask your coding agent to connect an email service and update the Better Auth email callbacks.
 
-### PostgreSQL Database on Vercel
+### Adding Google OAuth
 
-1. Go to <a href="https://vercel.com/dashboard" target="_blank">Vercel Dashboard</a>
-2. Navigate to the **Storage** tab
-3. Click **Create** → **Postgres**
-4. Choose your database name and region
-5. Copy the `POSTGRES_URL` from the `.env.local` tab
-6. Add it to your `.env` file
+Google OAuth is no longer the default, but adding it back is straightforward. Ask your coding agent:
 
-### Google OAuth Credentials
+```text
+Add Google OAuth to this Better Auth setup. Keep email/password login enabled, add the Google provider, update the auth UI, and document the required Google environment variables.
+```
 
-1. Go to <a href="https://console.cloud.google.com/" target="_blank">Google Cloud Console</a>
-2. Create a new project or select an existing one
-3. Navigate to **Credentials** → **Create Credentials** → **OAuth 2.0 Client ID**
-4. Set application type to **Web application**
-5. Add authorized redirect URIs:
-   - `http://localhost:3000/api/auth/callback/google` (development)
-   - `https://yourdomain.com/api/auth/callback/google` (production)
-6. Copy the **Client ID** and **Client Secret** to your `.env` file
+Your agent should update the Better Auth config, add the required `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` variables, and adjust the login UI.
 
-### OpenRouter API Key
+## Build With an Agent
 
-1. Go to <a href="https://openrouter.ai/" target="_blank">OpenRouter</a>
-2. Sign up or log in to your account
-3. Navigate to **Settings** → **Keys** or visit <a href="https://openrouter.ai/settings/keys" target="_blank">Keys Settings</a>
-4. Click **Create Key** and give it a name
-5. Copy the API key and add it to your `.env` file as `OPENROUTER_API_KEY`
-6. Browse available models at <a href="https://openrouter.ai/models" target="_blank">OpenRouter Models</a>
+This starter is designed to be used with coding agents. The generated project includes instructions that tell agents how to plan, ask questions, split work, use sub-agents when useful, follow the design system, and verify changes.
 
-### File Storage Configuration
+- `AGENTS.md` is the main instruction file for Codex, Cursor, and other agent-compatible tools.
+- `CLAUDE.md` points Claude users to the same project guidance.
+- `.agents/skills/` and `.claude/skills/` include optional workflows for more specialized tasks.
+- `DESIGN.md` defines the UI design system agents should follow.
 
-The project includes a flexible storage abstraction that automatically switches between local filesystem storage (development) and Vercel Blob storage (production).
+The default workflow does not require slash commands or a separate spec file.
 
-**For Development (Local Storage):**
-- Leave `BLOB_READ_WRITE_TOKEN` empty or unset in your `.env` file
-- Files are automatically stored in `public/uploads/`
-- Files are served at `/uploads/` URL path
-- No external service or configuration needed
+### Recommended Default Workflow
 
-**For Production (Vercel Blob):**
-1. Go to <a href="https://vercel.com/dashboard" target="_blank">Vercel Dashboard</a>
-2. Navigate to your project → **Storage** tab
-3. Click **Create** → **Blob**
-4. Copy the `BLOB_READ_WRITE_TOKEN` from the integration
-5. Add it to your production environment variables
+1. Install the starter and open the project in your coding-agent environment.
+2. Switch your agent tool to planning mode.
+3. Describe the app you want to build in plain language.
+4. Let the agent ask clarifying questions and shape a clear plan.
+5. Confirm the plan once the goal, scope, constraints, and success criteria are clear.
+6. Switch your agent tool to edit mode.
+7. Ask the agent to implement the approved plan.
+8. The main agent should split the work into parallel streams, silos, or feature chunks that fit within context.
+9. The agent should use sub-agents to implement those chunks in parallel where useful, then coordinate the results.
+10. The agent should run quality checks such as lint, typecheck, and build.
+11. Review the result in the browser and iterate.
 
-The storage service automatically detects which backend to use based on the presence of the `BLOB_READ_WRITE_TOKEN` environment variable.
+You do not need a special command for this default workflow. The project instructions already tell the agent how to plan, split implementation work, use sub-agents, and verify the result.
 
-## 🗂️ Project Structure
+## Starter Prompt
 
-```
-src/
-├── app/                    # Next.js app directory
-│   ├── api/               # API routes
-│   │   ├── auth/          # Authentication endpoints
-│   │   └── chat/          # AI chat endpoint
-│   ├── chat/              # AI chat page
-│   ├── dashboard/         # User dashboard
-│   └── page.tsx           # Home page
-├── components/            # React components
-│   ├── auth/             # Authentication components
-│   └── ui/               # shadcn/ui components
-└── lib/                  # Utilities and configurations
-    ├── auth.ts           # Better Auth configuration
-    ├── auth-client.ts    # Client-side auth utilities
-    ├── db.ts             # Database connection
-    ├── schema.ts         # Database schema
-    ├── storage.ts        # File storage abstraction
-    └── utils.ts          # General utilities
-```
+Use this as a first message to your coding agent after installing the starter:
 
-## 🔧 Available Scripts
+```text
+I am using the Agentic Coding Starter Kit. Treat the existing app as boilerplate that should be replaced by the product I describe.
 
-```bash
-npm run dev          # Start development server with Turbopack
-npm run build        # Build for production
-npm run start        # Start production server
-npm run lint         # Run ESLint
-npm run db:generate  # Generate database migrations
-npm run db:migrate   # Run database migrations
-npm run db:push      # Push schema changes to database
-npm run db:studio    # Open Drizzle Studio (database GUI)
-npm run db:dev       # Push schema for development
-npm run db:reset     # Reset database (drop all tables)
+Use the project instructions in AGENTS.md or CLAUDE.md. During planning, ask clarifying questions before making assumptions. During implementation, split the work into small chunks, use sub-agents where useful, follow DESIGN.md for UI, preserve the existing tech stack unless there is a good reason to change it, and run lint, typecheck, and build before finishing.
+
+What I want to build:
+[Describe your app here]
 ```
 
-## 📖 Pages Overview
+For example:
 
-- **Home (`/`)**: Landing page with setup instructions and features overview
-- **Dashboard (`/dashboard`)**: Protected user dashboard with profile information
-- **Chat (`/chat`)**: AI-powered chat interface using OpenRouter (requires authentication)
+```text
+What I want to build:
+A lightweight CRM for solo consultants. It should let users manage clients, track deals, write notes, set follow-up reminders, and view a simple dashboard of open opportunities.
+```
 
-## 🚀 Deployment
+## When to Use Specs
 
-### Deploy to Vercel (Recommended)
+For most POCs and MVPs, the normal agent workflow is enough. Use a spec when the feature is large, long-running, risky, or needs to be split across multiple implementation sessions.
 
-1. Install the Vercel CLI globally:
+The starter includes two skills for that workflow:
 
-   ```bash
-   npm install -g vercel
-   ```
+- `create-spec`: turns a planning conversation into `specs/{feature}/` with requirements, task files, dependency waves, and manual action notes.
+- `implement-feature`: reads a spec folder and coordinates implementation wave by wave with review gates.
 
-2. Deploy your application:
+Use this workflow when:
 
-   ```bash
-   vercel --prod
-   ```
+- the feature spans many files or modules
+- multiple agents should work in parallel
+- the implementation may take more than one session
+- you need resumable progress tracking
+- you want a written implementation record before coding starts
 
-3. Follow the prompts to configure your deployment
-4. Add your environment variables when prompted or via the Vercel dashboard
+Example agent request:
 
-### Production Environment Variables
+```text
+Create a spec for the billing and subscriptions feature we just planned. Break it into parallel implementation waves and include any manual setup steps.
+```
 
-Ensure these are set in your production environment:
+Then:
 
-- `POSTGRES_URL` - Production PostgreSQL connection string
-- `BETTER_AUTH_SECRET` - Secure random 32+ character string
-- `GOOGLE_CLIENT_ID` - Google OAuth Client ID
-- `GOOGLE_CLIENT_SECRET` - Google OAuth Client Secret
-- `OPENROUTER_API_KEY` - OpenRouter API key (optional, for AI chat functionality)
-- `OPENROUTER_MODEL` - Model name from OpenRouter (optional, defaults to openai/gpt-5-mini)
-- `NEXT_PUBLIC_APP_URL` - Your production domain
-- `BLOB_READ_WRITE_TOKEN` - Vercel Blob token (optional, uses local storage if not set)
+```text
+Implement the billing and subscriptions spec from specs/billing-subscriptions.
+```
 
-## 🎥 Tutorial Video
+## Project Structure
 
-Watch my comprehensive tutorial on how to use this agentic coding boilerplate to build AI-powered applications:
+```text
+src/
+├── app/
+│   ├── (auth)/
+│   │   ├── forgot-password/
+│   │   ├── login/
+│   │   ├── register/
+│   │   └── reset-password/
+│   ├── api/
+│   │   ├── auth/
+│   │   ├── chat/
+│   │   └── diagnostics/
+│   ├── chat/
+│   ├── dashboard/
+│   ├── profile/
+│   ├── layout.tsx
+│   └── page.tsx
+├── components/
+│   ├── auth/
+│   ├── ui/
+│   ├── site-footer.tsx
+│   └── site-header.tsx
+├── hooks/
+└── lib/
+    ├── auth.ts
+    ├── auth-client.ts
+    ├── db.ts
+    ├── env.ts
+    ├── schema.ts
+    ├── session.ts
+    ├── storage.ts
+    └── utils.ts
+```
 
-<a href="https://youtu.be/JQ86N3WOAh4" target="_blank" rel="noopener noreferrer">📺 YouTube Tutorial - Building with Agentic Coding Boilerplate</a>
+Important root files:
 
-## 🤖 Claude Code Commands
+- `AGENTS.md`: coding-agent behavior rules
+- `CLAUDE.md`: Claude entrypoint for the same guidance
+- `DESIGN.md`: UI design system and component guidance
+- `drizzle.config.ts`: Drizzle migration configuration
+- `docker-compose.yml`: local PostgreSQL service
+- `env.example`: environment variable template
+- `components.json`: shadcn/ui configuration
 
-This project includes custom slash commands for [Claude Code](https://claude.ai/code) that streamline feature development with GitHub integration.
+## Available Scripts
 
-### Available Commands
+```bash
+pnpm dev           # Start the development server with Turbopack
+pnpm build         # Run migrations, then build for production
+pnpm build:ci      # Build without running migrations
+pnpm start         # Start the production server
+pnpm lint          # Run ESLint
+pnpm typecheck     # Run TypeScript without emitting files
+pnpm check         # Run lint and typecheck
+pnpm format        # Format the repository
+pnpm format:check  # Check formatting
+pnpm setup         # Run the setup script
+pnpm db:generate   # Generate Drizzle migrations
+pnpm db:migrate    # Run Drizzle migrations
+pnpm db:studio     # Open Drizzle Studio
+```
 
-| Command | Description |
-|---------|-------------|
-| `/create-feature` | Create a new feature specification with requirements and implementation plan |
-| `/publish-to-github` | Publish a feature to GitHub Issues and Projects |
-| `/continue-feature` | Continue implementing the next task for a GitHub-published feature |
-| `/checkpoint` | Create a comprehensive checkpoint commit with all changes |
+The repository also contains Drizzle push/reset helper scripts for local experimentation. For schema changes you intend to keep, prefer:
 
-### Prerequisites
+```bash
+pnpm db:generate
+pnpm db:migrate
+```
 
-Before using the GitHub-integrated commands:
+Do not use schema push as a replacement for migrations in real project work.
 
-1. **GitHub CLI**: Install and authenticate the GitHub CLI
-   ```bash
-   # Install (if needed)
-   brew install gh  # macOS
-   # or see https://cli.github.com/
+## Database Workflow
 
-   # Authenticate
-   gh auth login
+For local development:
 
-   # Add project scopes (required for /publish-to-github)
-   gh auth refresh -s project,read:project
-   ```
+```bash
+docker compose up -d
+pnpm db:migrate
+```
 
-2. **Claude Code**: Install Claude Code CLI from [claude.ai/code](https://claude.ai/code)
+When your app needs schema changes, ask your agent to update `src/lib/schema.ts`, generate a migration, and run it:
 
-### Typical Workflow
+```bash
+pnpm db:generate
+pnpm db:migrate
+```
 
-#### 1. Plan Your Feature
+If you deploy to Vercel or another hosted environment, set `POSTGRES_URL` in that environment before running migrations or building the app.
 
-Start a conversation with Claude Code and describe the feature you want to build:
+## AI Features
 
-```
-You: I want to add a user preferences page where users can update their display name,
-     email notifications, and theme preferences.
-```
+The starter uses the Vercel AI SDK with OpenRouter. Set these variables to enable AI chat:
 
-#### 2. Create Feature Specification
+```env
+OPENROUTER_API_KEY=sk-or-v1-your-key
+OPENROUTER_MODEL="openai/gpt-5-mini"
+```
 
-Once you've discussed the requirements, run:
+OpenRouter lets you switch models without changing the application code. Update `OPENROUTER_MODEL` when you want to try a different model.
 
-```
-/create-feature
-```
+## File Storage
 
-This creates a spec folder at `specs/{feature-name}/` containing:
-- `requirements.md` - What the feature does and acceptance criteria
-- `implementation-plan.md` - Phased tasks with checkboxes
+The starter includes a storage abstraction that can use local storage in development or Vercel Blob in production.
 
-#### 3. Publish to GitHub
+For local development, leave `BLOB_READ_WRITE_TOKEN` empty. Files are stored under `public/uploads/`.
 
-Publish the feature to GitHub for tracking:
+For Vercel Blob:
 
-```
-/publish-to-github
-```
+1. Create a Blob store in Vercel.
+2. Copy the `BLOB_READ_WRITE_TOKEN`.
+3. Add it to your production environment variables.
 
-This creates:
-- An **Epic issue** with full requirements
-- **Task issues** for each implementation step
-- A **GitHub Project** to track progress
-- **Labels** for organization
-- A `github.md` file with all references
+The app chooses the storage backend based on whether `BLOB_READ_WRITE_TOKEN` is configured.
 
-#### 4. Implement Tasks
+## Deployment
 
-Start implementing tasks one at a time:
+Vercel is the recommended deployment target.
 
-```
-/continue-feature
+```bash
+npm install -g vercel
+vercel --prod
 ```
 
-This command:
-1. Finds the next unblocked task (respecting dependencies)
-2. Updates the GitHub Project status to "In Progress"
-3. Implements the task following project conventions
-4. Runs lint and typecheck
-5. Commits with `closes #{issue-number}`
-6. Updates the issue with implementation details
-7. Moves the task to "Done" on the Project board
+Set the required production environment variables:
 
-Repeat `/continue-feature` for each task, or let Claude continue automatically.
+- `POSTGRES_URL`
+- `BETTER_AUTH_SECRET`
+- `NEXT_PUBLIC_APP_URL`
+- `OPENROUTER_API_KEY`, if using AI features
+- `OPENROUTER_MODEL`, if using AI features
+- `BLOB_READ_WRITE_TOKEN`, if using Vercel Blob
+- `POLAR_WEBHOOK_SECRET` and `POLAR_ACCESS_TOKEN`, if using Polar payments
 
-#### 5. Create Checkpoints
+The default `pnpm build` script runs database migrations before `next build`. If your CI or host should not run migrations during build, use `pnpm build:ci` and run migrations as a separate deployment step.
 
-At any point, create a detailed checkpoint commit:
+## Troubleshooting
 
-```
-/checkpoint
-```
-
-This stages all changes and creates a well-formatted commit with:
-- Clear summary line
-- Detailed description of changes
-- Co-author attribution
+### The app cannot connect to Postgres
 
-### Example Session
+Confirm Docker is running and start the database:
 
 ```bash
-# Start Claude Code in your project
-claude
+docker compose up -d
+```
+
+Then check that `POSTGRES_URL` in `.env` matches the database connection string.
 
-# Discuss feature requirements
-You: I need to add API rate limiting to protect our endpoints...
+### Auth reset or verification emails are not arriving
 
-# Claude helps plan, then you run:
-/create-feature
+In development, links are logged to the terminal. This is intentional. Connect an email provider before using password reset or verification in production.
 
-# Review the spec, then publish:
-/publish-to-github
+### AI chat is not working
 
-# Implement task by task:
-/continue-feature
-# ... Claude implements, commits, updates GitHub ...
+Set `OPENROUTER_API_KEY` and restart the dev server. Also confirm `OPENROUTER_MODEL` is a model available to your OpenRouter account.
 
-/continue-feature
-# ... next task ...
+### My agent is preserving too much boilerplate
 
-# When done, push to GitHub:
-git push
+Tell the agent directly that the starter UI is scaffolding and should be replaced:
+
+```text
+Replace the starter UI with the actual product UI. Do not keep setup checklists, placeholder navigation, demo content, or boilerplate copy unless I explicitly ask for it.
 ```
 
-### Without GitHub Integration
+### I need Google login
 
-If you prefer not to use GitHub, you can still use `/create-feature` to create specs, then manually work through the `implementation-plan.md` checkboxes. The `/continue-feature` command also supports offline mode, tracking progress directly in the markdown file.
+Ask your agent to add Google OAuth through Better Auth while keeping email/password enabled. You will need Google OAuth credentials and production callback URLs.
 
-### Command Files Location
+## Video Tutorial
 
-Commands are defined in `.claude/commands/`:
-```
-.claude/commands/
-├── checkpoint.md
-├── continue-feature.md
-├── create-feature.md
-└── publish-to-github.md
-```
+Watch the original walkthrough:
+
+[Agentic Coding Boilerplate Tutorial](https://youtu.be/JQ86N3WOAh4)
 
-You can customize these commands or add new ones following the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code).
+Some details in older videos may differ from the current starter. This README is the source of truth for the current default workflow.
 
-## 🤝 Contributing
+## Support This Project
 
-1. Fork this repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
+If this starter kit helped you build something useful, you can support the project here:
 
-## 📝 License
+[Buy me a coffee](https://www.buymeacoffee.com/leonvanzyl)
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+## Contributing
 
-## 🆘 Need Help?
+1. Fork this repository.
+2. Create a feature branch.
+3. Make your changes.
+4. Run the relevant checks.
+5. Open a pull request.
 
-If you encounter any issues:
+## License
 
-1. Check the [Issues](https://github.com/leonvanzyl/agentic-coding-starter-kit/issues) section
-2. Review the documentation above
-3. Create a new issue with detailed information about your problem
+This project is licensed under the MIT License.
 
----
+## Need Help?
 
-**Happy coding! 🚀**
+- Check the repository issues: [github.com/leonvanzyl/agentic-coding-starter-kit/issues](https://github.com/leonvanzyl/agentic-coding-starter-kit/issues)
+- Review `AGENTS.md`, `CLAUDE.md`, and `DESIGN.md`
+- Open a new issue with the exact setup steps, error output, and environment details