# Plain Framework — New Project Setup

You are helping a developer create a new Plain web framework project.
Plain is a Python web framework — a fork of Django, redesigned for agentic development.

## Step 1: Ask what they want to build

Ask the user what they want to build. Based on their answer, recommend one of:

- **App starter** (default) — Full-featured app with database, auth, admin, Tailwind CSS. Best for most projects.
- **Bare starter** — Minimal setup with just views and templates. No database. Good for simple sites, APIs, or learning the basics.

If the user describes something that needs a database, users, or authentication, recommend the app starter.
If they want something simple or are just exploring, recommend bare.

## Step 2: Create the project

Check the current directory:

- **Empty or nearly empty directory** (e.g., user ran `mkdir my-app && cd my-app` first): Use `uvx plain-start .` to scaffold into the current directory. The project name will be the directory name.
- **Existing Plain project** (has `pyproject.toml` with `plain`): Tell the user they're already in a Plain project. Ask if they want to create a new one — if so, ask where.
- **Otherwise**: Ask the user what they want to name their project (suggest a name based on what they described). Figure out where to create it — check for common project directories (`~/Developer`, `~/Projects`, `~/Code`, `~/src`), or ask the user. If they just want to try things out, suggest `/tmp`. **Confirm the directory with the user before proceeding.** Then run `uvx plain-start <project-name>`.

For the starter type:
- App starter (default): `uvx plain-start <name>` or `uvx plain-start .`
- Bare starter: add `--type bare`

If the command fails because `uvx` or `uv` is not found, briefly explain that uv is a fast Python package manager (https://docs.astral.sh/uv/) that handles Python versions, dependencies, and virtual environments. Then help them install it: `curl -LsSf https://astral.sh/uv/install.sh | sh`. Then retry.

If you created the project in a subdirectory, use `cd` in subsequent commands (e.g., `cd /path/to/project && uv run plain dev`).

## Step 3: Start the dev server

Run `uv run plain dev` to start the development server.

If the app starter fails because Docker is not available (needed for a local Postgres database), let the user know they can install Docker from https://www.docker.com/products/docker-desktop/ and try again.

Verify the server is up by running `curl -sSk https://<project-name>.localhost:8443/` and checking for a 200 response. Once confirmed, open the URL in the user's browser with `open https://<project-name>.localhost:8443` (macOS) or `xdg-open` (Linux). Tell them the server auto-reloads when files change.

## Step 4: Plan the first features

The project is running. Now help the user start building what they described in step 1.

Enter plan mode to outline the first steps — what models to create, what views and templates to add, what packages to install. Confirm the plan with the user before writing any code.

Use `uv run plain docs <package>` to look up the APIs you need. The project includes a `.plain/` directory with agent rules and skills that will guide you on Plain conventions.

## Useful links

- Docs: https://plainframework.com/docs/
- Getting started: https://plainframework.com/start/
- GitHub: https://github.com/dropseed/plain
- Packages: https://plainframework.com/docs/plain/plain/