---
name: init-project
description: Initialize a new full-stack app with Bun, Next.js App Router and React Compiler, shadcn/ui, Convex, and Convex Auth with Google OAuth only. Set up GitHub source hosting and GitHub-triggered Vercel deployments. Use for new project setup or explicit adoption of this stack, not routine changes to existing apps.
---

# Init project

Build the requested app on this stack and leave a working, documented project. Honor explicit user changes to these defaults. Do not migrate an existing app merely because this skill is available.

## Defaults

- Bun for installs, scripts, and the committed Bun lockfile.
- Next.js App Router, TypeScript, Tailwind CSS, and React Compiler enabled using the installed Next.js version's supported configuration.
- shadcn/ui for UI components. Initialize its configuration and add only the components the app uses.
- Convex for the database and backend.
- Convex Auth via `@convex-dev/auth`, with Google as the only sign-in provider. Do not substitute Clerk, Better Auth, standalone NextAuth, passwords, email links, or anonymous login.
- GitHub for source code and Vercel's GitHub integration for frontend hosting.
- All preview and production code deployments originate from commits pushed to GitHub. The Git-triggered Vercel build deploys the matching Convex backend too.

## Understand the project

Read applicable repository instructions and inspect the destination before scaffolding. Preserve existing files and unrelated changes. If an app already exists, use it only when the user explicitly wants this setup applied there; otherwise choose a new directory.

Infer the app's purpose and project name from the request. Ask only for missing choices that block work. Establish only the accounts and resources needed for the requested phase before creating them. For local development, identify the Convex development team and project. For authorized remote setup, also identify the GitHub owner and repository, visibility, Vercel team and project, and production branch. Skip GitHub and Vercel account questions for local-only work. Reuse selected resources. Prefer a private repository when visibility is unspecified, and state that assumption. Do not assume access to a teammate's accounts.

Use tools, CLIs, or dashboards available in the current environment. This skill must work without proprietary MCP tools or other installed skills. Check current official docs and CLI help before choosing scaffold flags or version-sensitive integrations. If relevant platform skills are available, use them for detailed mechanics without changing this skill's stack or Git deployment rule.

Ask early for the Google OAuth **Client ID and Client Secret**. Explain that these must come from a Google Cloud OAuth client of type Web application. Offer either direct entry into the selected Convex deployment's environment-variable settings or an ignored local credentials file. Never require pasting a secret into chat. If they do not have credentials yet, help configure the consent screen and client after the Convex callback URL is known. Continue scaffolding while waiting; never claim Google sign-in works before testing it.

## Scaffold and connect

1. Scaffold the current stable Next.js release with compatible React packages using Bun. Enable React Compiler, TypeScript, Tailwind, and App Router. Keep dependency versions and a Bun package-manager version recorded in the project and commit the lockfile.
2. Initialize shadcn/ui using its current CLI. Build the requested initial UI, including a Google sign-in screen, authenticated app area, and sign-out control. Show loading and error states. Avoid adding unrelated product features.
3. Install Convex with `bun add convex`, then initialize a separate Convex development deployment with `bunx convex dev`. This development sync is allowed; it must never target production. Keep development credentials out of Vercel production settings and committed files.
4. Read [auth-and-deployment.md](references/auth-and-deployment.md) before configuring auth or hosting. Install compatible Convex Auth dependencies using the currently documented `@auth/core` version rather than blindly installing its latest release.
5. Configure auth tables, `auth.config.ts`, a Google-only `auth.ts`, and the HTTP auth routes. Wire the Next.js server provider, client provider, and auth middleware or proxy using the supported integration for the selected Next.js release. Do not copy the Vite setup into Next.js.
6. Use the real Convex generated API and types. Enforce authentication and ownership on the backend for user data, including a small user-owned record if the app has no existing persistence flow. Derive ownership from the authenticated identity, never a user ID trusted from the browser. Use validators and indexes for the implemented queries and mutations.
7. Configure development OAuth, then test sign-in, session persistence after refresh, sign-out, and access to protected data. A hidden UI is not an authorization boundary.

Use local port 3000 when available. Use a custom tunnel only when the current user provides one. Do not copy a skill author's domains, organization names, credentials, or machine paths into another user's project.

## Keep deployment in Git

The permitted release path is:

```text
local changes -> commit -> push to GitHub
  -> Vercel Git build -> Convex deploy + Next.js build -> hosted app
```

Prepare the implementation and checks before publishing. A request to initialize locally does not authorize creating remote repositories or publishing a site. A request to create the GitHub repository and deploy authorizes those steps within the selected accounts; do not ask again for already-authorized work.

- Initialize Git when needed, configure the intended GitHub remote, and review the files being committed. Use explicit paths so unrelated changes are excluded.
- Connect Vercel to that repository and set its production branch. Configure the Bun install command and the Git build command from the reference before the first build.
- Provision production Convex configuration, auth keys, OAuth settings, and the scoped Vercel deployment key. Configuration changes and auth key initialization are setup operations; they must not upload application code from the local machine.
- Initial Vercel repository import can build the already-pushed commit. After setup, trigger releases and retries through an authorized new commit and push. Prefer a real corrective change; use an empty retrigger commit only when needed and within existing commit/push authorization.
- Never run `vercel`, `vercel deploy`, `vercel --prod`, direct deployment APIs, deploy hooks, dashboard redeploys, or local `convex deploy` to publish code. Do not run `convex dev --prod`. Running `convex deploy` inside Vercel's Git-triggered build is required and permitted.
- Configure preview isolation before enabling branch previews. Do not give previews the production Convex deploy key or point previews at production data. If isolated preview auth is not configured, disable preview deployments and explain what remains.
- After pushing, verify the GitHub commit SHA matches Vercel's deployment and inspect the frontend build and Convex deployment result. A successful push is not a successful release. Repair failures through Git.

## Verify and hand off

Run lint and TypeScript checks for frontend and Convex code using actual package scripts. Add working `lint` and `typecheck` scripts when absent. Do not run a local production build by default; Vercel runs the release build. Run additional targeted checks when implementation changes warrant them.

Use a browser to verify the local app and, after an authorized release, the hosted app. Check Google sign-in, refresh, sign-out, protected-route handling, and a real Convex read/write. Check unauthenticated backend access and cross-user access where user-owned data exists. Ask the user to complete interactive Google authentication if tools cannot do so. State the exact unverified behavior if interactive access is unavailable.

Write concise project setup documentation, a secret-free environment-variable example, and repository `AGENTS.md` instructions preserving this stack and Git-only deployment path. Document which values belong in Convex versus Vercel, local run/check commands, OAuth callback URLs, and any remaining setup. Ensure `.env*` credentials and local tooling state are ignored while the example file is tracked.

Report the local path, GitHub repository, Vercel URL, Convex development/production targets, completed checks, and remaining blockers. Distinguish prepared configuration, pushed code, successful deployment, and verified authentication. Never include credential values in the handoff.