feat(ci): add minimal GitHub workflow and document template structure

- add .github/workflows/ci.yml to build dev and app images
- run ruff check, ruff format --check, and pytest in CI
- document GitHub CI checks in README
- add a short project structure section for template users

Author: jamm1985

.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  build-and-check:
+    runs-on: ubuntu-latest
+    env:
+      DOCKER_PLATFORM: linux/amd64
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Set up Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build dev and app images
+        run: docker compose build dev app
+
+      - name: Ruff lint
+        run: docker compose run --rm dev ruff check .
+
+      - name: Ruff format check
+        run: docker compose run --rm dev ruff format --check .
+
+      - name: Run tests
+        run: docker compose run --rm dev pytest -q

README.md

@@ -9,6 +9,7 @@
 
 * [About the Template](#about-the-template)
 * [Features](#features)
+* [Project Structure](#project-structure)
 * [Tested with](#tested-with)
 * [Prerequisites](#prerequisites)
 * [Quickstart](#quickstart)
@@ -20,6 +21,7 @@
   * [5. Update dependencies when needed](#5-update-dependencies-when-needed)
   * [Build and run your application](#build-and-run-your-application)
   * [Optional: Use `dev` for checks and experiments](#optional-use-dev-for-checks-and-experiments)
+  * [GitHub CI checks](#github-ci-checks)
   * [Optional: Run Codex or Gemini (see more examples below)](#optional-run-codex-or-gemini-see-more-examples-below)
   * [Optional: Run JupyterLab](#optional-run-jupyterlab)
 * [💻 AI-Powered CLI Workflow (Gemini & Codex)](#-ai-powered-cli-workflow-gemini--codex)
@@ -69,6 +71,22 @@ Use it as-is or tailor it to match your team's development workflow.
 * Simple to extend with Jupyter, SQL drivers, and more
 * Works identically on any machine with Docker
 
+## Project Structure
+
+```text
+.
+├── .github/workflows/ci.yml      # GitHub CI: build dev/app, run Ruff + pytest
+├── src/sample/main.py            # Example application module
+├── tests/sample/test_main.py     # Example pytest tests to extend in your project
+├── Dockerfile                    # Multi-stage images (base, dev, vim-ide, app)
+├── compose.yaml                  # Local service orchestration for template workflows
+├── pyproject.toml                # Poetry dependencies and tool configuration
+├── poetry.lock                   # Locked dependency graph
+└── README.md                     # Setup and usage documentation
+```
+
+This layout is intentionally minimal so it can be extended for any project.
+
 ## Tested with
 
 * **Docker**: `27.3.1` – `29.2.1`
@@ -213,6 +231,18 @@ docker compose run --rm dev ruff check
 docker compose run --rm dev ruff format --check
 ```
 
+### GitHub CI checks
+
+This template includes a minimal GitHub Actions workflow in
+`.github/workflows/ci.yml` that:
+
+* builds `dev` and `app` images
+* runs `ruff check .`
+* runs `ruff format --check .`
+* runs `pytest -q`
+
+The same pattern can be easily extended for any other CI system.
+
 If you’re running as the non-root user and want to try extra system packages
 before baking them into the image, use `sudo`: