Django seedkit

How this skill works

Two paths:

• New project (empty dir, only .git/ or stub README): run §2 → §8 in order.
• Existing project (has pyproject.toml and Django code): skip §2–§4. Read references/existing-project.md for the inventory workflow, then jump to §5/§6 and ask only about missing components.

Before either path, run uv --version to confirm uv is installed (references/uv.md).

Every question below names the reference that answers it — read that one file before applying the step, and no others.

For every question that involves a third-party package: 1–2 sentences from the reference's intro on what it adds beyond stock Django, then ask. none (or no) is always a valid answer.

Use answers already given. Before asking any question, scan the user's initial request (and anything they've said since) for the answer. If it's there — explicit ("use PostgreSQL", "with Celery", "no auth") or unambiguous from context — take it as given, note the decision in one line, and move on. Don't re-ask to confirm. Only ask when the answer is genuinely missing or ambiguous.

Preflight — read these before the first tool call of a new-project run: references/new-project.md, references/database.md, and references/conventions.md (the cross-file contract: env var names, Redis DB map, prod compose service shape, SameSite rule, Python pins).

Instructions

1. Open the conversation

Name the groups you'll walk through — Project Foundation (§2), then Developer Experience, Auth & Accounts, Data & Storage, Background & Email, Frontend & Site Basics, SaaS / Product, Real-time (§5.1–5.7), then Production & Deploy (§6) — one sentence each. For existing projects: first follow references/existing-project.md and note what's already detected per group. Invite the user to begin.

2. Project Foundation — new projects only, one question at a time, in order

1. Project name + one-line purpose (the explicit two-answer pair).
2. Settings layout: single settings.py or split base/local/production. → references/new-project.md
3. Database: SQLite or PostgreSQL. → references/database.md
4. Request handling: wsgi / asgi / asgi+channels. Default wsgi. Decide now — Dockerfile CMD, server choice, and the manage.py/wsgi.py/asgi.py settings defaults all hinge on this; switching later means rewriting deploy artefacts. See references/async.md (and references/realtime.md for the channels mode).
5. If Postgres: host Postgres or Postgres-in-Docker (docker-compose.yml for the local services). SQLite users skip. → references/docker.md
6. If the project has a docker-compose.yml (from step 5): dev loop — manage.py on the host via uv run, or in a web container via docker compose. Default host. → references/docker.md
7. Custom user model: yes / no — decide now (see references/custom-user.md).

Never bundle questions beyond the explicit pair in step 1.

3. Apply the foundation (new projects only)

Generate files from the matching references. .env DATABASE_URL must match DB + dev mode + dev loop (@localhost:5432 on the host, @db:5432 in the container). If custom user = yes, apply references/custom-user.md before the boot check. If DB=SQLite, also apply the production.py block from references/database.md (WAL + IMMEDIATE PRAGMAs) — settings tuning, not a user-facing question.

4. Foundation smoke — agent-driven, new projects only

Run these yourself; do not ask the user. The goal is to catch foundation bugs before piling on add-ons, without making the user type uv run … commands that §5.1 may replace minutes later.

• uv run manage.py migrate (start the local Postgres service first with docker compose up -d db when DB=Postgres-in-Docker).

• Start uv run manage.py runserver --noreload in the background. --noreload drops the StatReloader so the listener is ready sooner; a sleep 2 then curl can still race on slow CI, so poll — and test the flag after the loop, because a bare for … curl … done exits 0 even when the server never came up:

  for i in 1 2 3 4 5; do curl -sf http://127.0.0.1:8000/admin/login/ > /dev/null && up=1 && break; sleep 1; done
  [ -n "$up" ] || echo "BOOT CHECK FAILED"
  

• Stop the server. Use the recorded PID from the background-launch step (kill "$PID"); don't use kill %1 (no job control in non-interactive bash) or pkill -f manage.py (matches the parent harness process).

Container dev loop (§2.6): docker compose up -d --wait covers the server too — web has its own healthcheck and depends_on gates it on Postgres. Then docker compose exec web python manage.py migrate, the same curl poll, and docker compose logs web on a failure. There is no background PID; docker compose down stops it.

If migrate or the curl fails, fix the foundation before proceeding to §5. createsuperuser and the browser login move to §7 — they need a stable task runner name and a real browser, neither of which exists yet.

5. Add-ons — one group at a time, one question at a time

For new projects: ask every question. For existing projects: only ask about components not already detected in §1; confirm and skip the rest.

5.1 Developer Experience

1. Ruff lint: yes / no. Default no. → references/lint.md
2. Test runner: pytest or stock manage.py test. Default no (stock). → references/pytest.md
3. Type checking with pyright + django-stubs: yes / no. Default no. → references/typecheck.md
4. Pre-commit hooks: yes / no. Default no — recommend yes if lint=yes; wires whichever of lint / format / typecheck were chosen. → references/pre-commit.md
5. Devcontainer: yes / no. Default no. Wraps a Python image with uv pre-installed so VS Code / Codespaces / JetBrains Gateway open the project ready to run. → references/devcontainer.md
6. Debug toolbar: django-orbit / django-silk / none. Default none. → references/dev-tools.md
7. Browser auto-reload via django-browser-reload: yes / no. Default no. → references/dev-tools.md
8. DB safety: any of django-zeal / django-migration-linter / django-test-migrations. Default none. Skip django-test-migrations if pytest = no. → references/dev-tools.md
9. django-extensions: yes / no. Default no. → references/dev-tools.md
10. Structured logging via structlog: yes / no. Default no. → references/logging.md
11. Task runner: mise / just / make / poe / none. Default mise (recommended). Detect what's installed with command -v and offer the first hit; mention the others. See references/dev-tasks.md.

5.2 Auth & Accounts

1. Auth: django-allauth / django-mail-auth / none. Default none. → references/auth.md
2. django-axes brute-force lockout: yes / no. Default yes. Skip if auth = none. → references/auth-hardening.md
3. 2FA: yes / no. Default no. Skip if auth = none. When yes: built-in allauth.mfa if auth = allauth (via django-allauth[mfa] extra — never allauth-2fa, which is unmaintained), else django-otp. → references/auth-hardening.md

5.3 Data & Storage

1. Cache backend: sqlite / redis / locmem / none. Default sqlite when DB=SQLite, else locmem. sqlite wires a separate cache.sqlite3 + CacheRouter + DatabaseCache (see references/database.md); redis adds django-redis (references/redis.md); locmem is the per-process in-memory backend.
2. Static + media storage: whitenoise / s3 / none. Default none — required before production but not for first boot. → references/storage-whitenoise.md / references/storage-s3.md

5.4 Background & Email

1. Background tasks: celery / django.tasks / none. Default none. Django Tasks is the core API with in-process backends; use Celery for a worker queue. → references/tasks-celery.md / references/tasks-django.md
   • If django.tasks: periodic tasks via django-crontask? Default no. → references/tasks-django-cron.md.
2. Email backend: console / smtp / mailpit / anymail / none. Always ask — every project sends mail eventually (password resets, error reports, allauth verification). → references/email.md
   • If backend ≠ none: HTML email base template + send_test_email command? Default no.

5.5 Frontend & Site Basics

1. Frontend: tailwind / none. Default none. → references/tailwind.md
   • If tailwind: custom 404/403/500 templates? Default no.
   • If tailwind: DaisyUI components? No default — always ask explicitly.
   • If tailwind: favicon (agent-drawn SVG matching the project)? Default yes. → references/favicon.md
2. SEO basics (meta/OG tags + sitemap): yes / no. Default no — only for public-facing sites. Skip if Frontend = none (the meta block needs base.html). → references/seo.md
3. i18n (gettext, LocaleMiddleware, makemessages): yes / no. Default no — cost of adding later is real. → references/i18n.md
4. CORS: yes / no. Default no — only when there's a separate frontend on a different domain. → references/cors.md
5. robots.txt: yes / no. Default no — only for public-facing sites. → references/robots.md

5.6 SaaS / Product

1. REST API: django-modern-rest / django-bolt / none. Default none. → references/rest.md for the comparison; when the user already named a library, skip it and read references/rest-modern-rest.md or references/rest-bolt.md directly.
2. Billing: stripe (raw SDK) / dj-stripe / none. Default none. → references/billing.md
3. Analytics: goatcounter / umami / shynet / ga4 / none. Default none. → references/analytics.md

5.7 Real-time

Only ask when request handling is asgi+channels — Foundation §2.4 for new projects, the value references/existing-project.md §2 detected for existing ones. Otherwise skip the whole group.

1. Channel layer: channels-redis / InMemoryChannelLayer. Default channels-redis. In-memory is dev-only — it doesn't span processes, so any horizontal scale or separate ASGI worker process breaks broadcast. → references/realtime.md

6. Production & Deploy — one question at a time

1. Security settings: yes / no. Default no. → references/security.md
   • If yes: Content Security Policy using Django's built-in CSP support? Default yes. → references/csp.md
2. Health check endpoints (/healthz, /readyz): yes / no. Default yes. Apply before the deploy target so the deploy reference can wire the matching probe block in compose / fly.toml / nginx. → references/healthcheck.md
3. Error reporting: bugsink / sentry / glitchtip / none. Default none. → references/error-reporting.md
4. GDPR helpers: yes / no. Default no. → references/gdpr.md
5. CI on GitHub Actions: yes / no. Default no. → references/ci.md
6. Deploy target: vps / managed / github-ssh / none. Default none. → references/deploy-vps.md / references/deploy-managed.md / references/deploy-github-ssh.md Any target other than none applies references/docker.md first — all three deploy references build on its multi-stage production image. With none, skip the production Dockerfile; the local services compose from §2.5 / §5.3 stands on its own (with the container dev loop, so does the dev stage — a Dockerfile holding only that stage is the expected output).
   • If vps or github-ssh: database backups via django-dbbackup? Default yes. → references/dbbackup.md Both deploy to self-managed hosts. Skip for managed — those platforms ship native backups. Also skip when DB=SQLite + deploy=vps if Litestream is already wired (see references/database.md) — Litestream replicates every WAL frame, so dbbackup snapshots are redundant.

7. Final smoke — user-driven, new projects only

After §6, ask the user to run, using the task-runner names from §5.1 if one was applied (else uv run manage.py …):

• createsuperuser (interactive — the user runs it themselves).
• collectstatic --noinput only if a static-files add-on was applied.
• Open /admin/ in a browser and sign in with the new superuser.

Wait for the user to confirm the browser login works before §8.

8. README + agent context

After applying any reference, append the decision and any new commands to README.md. Finalize at the end of the run with stack summary and key commands (install, test, migrate, run, deploy). Don't hardcode dependency versions — read them from pyproject.toml. If a task runner was applied (§5.1), show task-runner names (mise run dev, just test) in the README's main command list — not the raw uv run … invocations.

If a deploy target was applied (§6.6), copy the deploy command block from the matching references/deploy-*.md verbatim into a ## Deploy section in README.md. The block includes the one-shot manage.py migrate step that runs before docker compose up -d — without it, the first up -d --build hits an empty database and every page 500s.

For new projects only (no question — always):

• Write AGENTS.md: one line per stack decision (layout, DB, request handling, each applied add-on), the project layout tree, and the same key-commands block the README gets. Coding agents load it as project context, so keep it factual and short — no marketing prose.
• Write CLAUDE.md containing exactly one line: @AGENTS.md.
• Append a final line to README.md: Built with [Seedkit](https://github.com/viewflow/seedkit).

Skip all three on existing-project runs.

Common pitfalls

Each rule has a why so you can judge edge cases.

Snippet integrity

• Use snippets verbatim. Don't drop lines that look obvious or redundant — DEFAULT_AUTO_FIELD and gated env defaults. They look optional and are not.
• The fail-fast idiom for env vars is default=<dev-value> if DEBUG else env.NOTSET. env.NOTSET raises ImproperlyConfigured naming the variable when the env var is missing in prod.
• Don't reimplement django-environ (no manual .split(","), no leftover import os).

Cross-file consistency

• Shared names and shapes (env vars, Redis DBs, compose service fragments) follow references/conventions.md. If two references seem to disagree, conventions.md wins.

Env vars and .env.example

• Always DJANGO_DEBUG / DJANGO_SECRET_KEY / DJANGO_ALLOWED_HOSTS — these names are referenced across many references.
• When adding an add-on, append every env var its reference reads to .env.example so the file stays the canonical list.
• .env.example comments belong on their own lines, never trailing the value. django-environ reads everything after = verbatim.

App layout

• Don't create an app dir named after the project unless asked.
• tasks.py must live inside a registered Django app, not at project root or under config/. Import it from AppConfig.ready() so Django Tasks registers the decorated functions. When a fresh project has no app yet, don't auto-create one unless the user asked for a task example.

After startproject / uv init / startapp

• Set requires-python = ">=3.12" in pyproject.toml immediately after uv init, before the first uv add. The host-derived pin (>=3.14 on recent machines) refuses Django 6.1.
• After inserting the env-driven DATABASES = {...} line in references/new-project.md (Option A in settings.py, Option B in base.py), delete the original hardcoded DATABASES block + # Database comment that startproject emitted. Bottom wins; leaving both makes DATABASE_URL dead code.
• After startapp <name>, if Ruff is enabled, run uv run ruff check --fix . && uv run ruff format ., in that order — startapp ships admin.py / views.py / tests.py with stub imports that fail F401, and dropping an import leaves a blank first line only the formatter clears. Verify with uv run ruff format --check .; ruff check alone reports those files clean.
• Run startapp <name> before adding <name> to INSTALLED_APPS. manage.py startapp imports settings; if the app is already listed but the directory doesn't exist, the import fails with ModuleNotFoundError. Same for any package a settings block references (e.g. orbit.handlers.OrbitLogHandler in LOGGING) — uv add it before the next startapp runs, or that import fails too.
• If i18n = no, remove the USE_I18N = True line and the # Internationalization comment block that startproject emits. Harmless to leave, but the reference's settings are single-language by default and the orphan block invites confusion.

uv run vs python invocation

• On the host (dev, local commands, smoke checks): uv run manage.py …. uv resolves the project venv.
• Inside any Docker container (dev compose exec, prod compose run, Fly release_command, devcontainer postAttach): python manage.py …. /opt/venv/bin is on PATH; the multi-stage runtime image (python:3.X-slim-trixie) has no uv binary, so uv run breaks there.

Add-on scope

• Don't add packages the user didn't ask for. django-extensions is an explicit add-on question — apply only if the user said yes.