scaffold-app

Scaffold App

The user wants to start a new project from scratch. They have no coding experience and are staring at an empty folder. Get them to a working, visible application as fast as possible.

Step 1: Understand the Goal

Ask the user:

• What are you building? (one sentence is fine)
• Who is it for?
• Do you have a preference for how it looks? (dark mode, light mode, specific colors)

If they are unsure about technology choices, recommend:

• Next.js + TypeScript + Tailwind CSS for web apps
• React Native / Expo for mobile apps
• FastAPI + Python for backend-only APIs

Step 2: Scaffold

Generate the project with these commands (adapt to the chosen stack):

npx create-next-app@latest my-app --typescript --tailwind --app --src-dir
cd my-app

Then immediately create:

1. A landing page with a heading, subtitle, and one call-to-action button
2. A second page linked from the landing page (the core feature page, even if empty)
3. A clean layout with navigation between the two pages

Step 3: Generate AGENTS.md

AGENTS.md is a "README for agents": a dedicated, predictable place to provide context and instructions that help AI coding agents work on the project. It works across Cursor, Claude Code, OpenAI Codex, Google Jules, Aider, Windsurf, GitHub Copilot, and many more tools (see agents.md for the full list).

Create an AGENTS.md file at the project root with these sections, filled in based on the user's project:

# AGENTS.md

## Project Overview
[One paragraph: what this project does and who it's for]

## Setup Commands
- Install deps: `pnpm install`
- Start dev server: `pnpm dev`
- Build for production: `pnpm build`
- Run linter: `pnpm lint`
- Run tests: `pnpm test`

## Tech Stack
- Framework: [e.g., Next.js 15 with App Router]
- Language: [e.g., TypeScript]
- Styling: [e.g., Tailwind CSS v4]
- Database: [e.g., Supabase, or "None yet"]
- Auth: [e.g., NextAuth.js, or "None yet"]
- Deployment: [e.g., Vercel]

## File Structure
- `app/` — Pages and layouts (App Router)
- `components/` — Reusable UI components
- `lib/` — Utility functions and shared logic
- `types/` — TypeScript type definitions
- `public/` — Static assets (images, fonts)

## Code Style
- TypeScript strict mode
- Functional components with hooks; no class components
- Server components by default; add "use client" only when needed
- kebab-case for file names, PascalCase for component names
- Validate all user input with Zod
- Use descriptive variable names (no abbreviations)

## Testing Instructions
- Run `pnpm test` to execute the full test suite
- Add or update tests for any code you change
- Fix any test or type errors until the suite is green
- After moving files or changing imports, run `pnpm lint`

## Security Considerations
- Never hardcode secrets or API keys; use `.env.local` and environment variables
- Never commit `.env.local` to version control
- Ask before database writes or destructive operations
- Ask before deploying to production
- Propose plans before large refactors

## PR Instructions
- Title format: `[feature/fix/chore] Short description`
- Always run `pnpm lint` and `pnpm test` before committing
- Keep diffs small and focused on a single change
- Include a manual test path in the PR description