Wagtail Start AI

This repository uses a static styleguide workflow for prototyping page types and reusable components. The styleguide defines layout, content fields, and editorial rules that map directly to Wagtail templates and models.

Development

• uv run python manage.py runserver starts the Django and Wagtail application
• uv run python manage.py migrate applies database changes
• uv run python manage.py test runs the Django test suite
• npm run dev watches app and styleguide assets and serves the styleguide at http://127.0.0.1:3001
• npm run build builds deployed app assets into app/static and styleguide assets into styleguide/build/assets
• npm run test runs the frontend smoke check by building both asset targets
• npm run format applies Python and frontend formatting
• npm run format-check runs non-mutating formatting checks

Styleguide workflow

• Source prototype pages live in styleguide/
• Shared frontend primitives live in frontend/shared/
• Deployed app assets are authored from frontend/app/ and built into app/static/
• Styleguide-only assets are authored from frontend/styleguide/ and built into styleguide/build/assets/
• Built output should not be edited by hand
• Use the styleguide to define page structure and editorial rules, then implement approved patterns in Wagtail templates, page models, and StreamField blocks only where needed
• Promote approved tokens, layout primitives, and interactions into shared or app-facing assets deliberately; do not point Wagtail templates at the raw styleguide bundle

Formatting

• Python formatting and lint fixes use Ruff through uv run ruff check --fix . and uv run ruff format .
• Frontend JavaScript, CSS, and build scripts use Biome through npm run format:frontend
• npm run format is the repo-wide write command
• npm run format-check is the repo-wide read-only check command
• Install the local final guard with uv run pre-commit install
• Verify the full hook set at any time with uv run pre-commit run --all-files

CI

GitHub Actions runs CI on pushes to main and on pull requests targeting main.

• format-check installs the Python and Node toolchains, syncs the locked dev dependencies, and runs npm run format-check
• frontend-build installs Node dependencies and runs npm run test
• django-tests syncs the locked Python dependencies and runs uv run python manage.py test on Python 3.12, 3.13, and 3.14

The project metadata and CI matrix support Python 3.12+ while the local default in .python-version remains Python 3.14.

Developer Docs

• The default workflow for this repository is a solo human developer collaborating with an AI agent; contributions from other human developers are also welcome when they follow the same documented workflow.
• Day-to-day onboarding and repo workflow: docs/developer-onboarding.md
• Pull request policy and required checks: CONTRIBUTING.md
• Notable repo-facing changes should be recorded in CHANGELOG.md
• Keep these docs in sync with code, setup, workflow, and editorial-rule changes; if a change affects documented behavior, update the relevant documentation in the same change.
• All pull requests should include a structured summary covering the goal, approach, affected areas, verification, documentation status, changelog status, and known risks or skipped checks.
• GitHub uses the repository pull request template in .github/pull_request_template.md to keep PRs consistent.