theslopmachine 0.6.2 → 0.7.1

package/assets/slopmachine/scaffold-playbooks/android-native-java.md

@@ -0,0 +1,203 @@
+# Android Native Java Scaffold Playbook
+
+Use this playbook for native Android requests unless the prompt explicitly requires Kotlin, Compose, or a different Android stack.
+
+## Goal
+
+Create a fast, repeatable Android scaffold that is:
+
+- native Android
+- baseline-only, not feature-complete
+- honest about offline/bootstrap/runtime constraints
+- portable broad-testable on Linux with Docker
+- safe by default on secrets and bootstrap data
+
+## Runtime contract
+
+- required Docker command: `docker compose up --build`
+- required broad test command: `./run_tests.sh`
+- both commands must be real and working
+- `./run_app.sh` may exist as a helper for host-side convenience, but it does not replace the required Docker baseline
+
+## Verified baseline notes
+
+From a real lab verification on 2026-04-14:
+
+- the current Android baseline does converge honestly in Docker without an emulator
+- `docker compose up --build -d --wait` reached a stable healthy state
+- the healthy state was a loopback-only artifact server serving the built APK from `artifacts/app-debug.apk`
+- `./run_tests.sh` reused the running container with `docker compose exec` for `:app:lintDebug` and `:app:testDebugUnitTest`, then smoke-checked the served APK
+- the observed containerized Gradle verification completed successfully with `BUILD SUCCESSFUL in 1m 42s`
+- the current practical proof boundary is: pinned toolchain + APK assembly + lint + JVM unit tests + artifact serving; it does **not** claim emulator or device runtime proof
+- the current Docker strategy is acceptable because the heavy Android SDK/toolchain layers are pre-baked and cached instead of being reinstalled on every rerun
+
+## Safe default stack
+
+- Android Gradle Plugin: `8.5.x`
+- Gradle wrapper: `8.7`
+- Java: `17`
+- `compileSdk = 34`
+- `targetSdk = 34`
+- `minSdk = 29`
+- Android Views by default unless the prompt explicitly requires Compose
+
+## Safe default libraries
+
+- AppCompat
+- Material
+- ConstraintLayout
+- Lifecycle
+- Room
+- JUnit
+
+Robolectric is **optional**, not mandatory. Use it only when the verified Linux/Docker baseline can run it without extra native-runtime breakage or flaky heavyweight downloads. If that is not true, fall back to JVM tests + lint + assemble and document the proof boundary honestly.
+
+Add security/storage libraries only when the prompt or selected baseline actually needs them.
+
+## Preferred repo shape
+
+- `app/`
+- `core/model/`
+- `core/rules/`
+- `core/data/`
+- `feature/*/`
+
+Only add deeper security/media/operator modules during scaffold when the requested technologies already make them necessary.
+
+## Required scripts
+
+- `./init_db.sh` when the app has database dependencies
+- `docker compose up --build`
+- `./run_tests.sh`
+- `./run_app.sh` when useful for host-side convenience
+
+## Bootstrap model
+
+- use one bootstrap source of truth
+- no committed plaintext bootstrap credentials
+- no `.env` files
+- if local bootstrap data is needed for dev/test, generate it only under ignored build output
+- if packaged seed data is needed, package only non-sensitive assets
+- app runtime must not contain duplicate hidden seed logic outside the chosen bootstrap path
+
+## Room and schema rules
+
+- enable `exportSchema = true` when Room is present
+- write schemas to a real repo-visible path such as `app/schemas/`
+- add a real schema verification task when Room is part of the baseline
+- route runtime/test/bootstrap through `./init_db.sh` when database setup exists
+
+## Docker runtime baseline
+
+For Android-on-Linux scaffolds, prefer a **toolchain image + bind-mounted workspace + stable support surface** instead of pretending Docker proves full device runtime.
+
+Recommended baseline shape from real verification:
+
+1. build a pinned Android toolchain image once
+2. pre-bake only the heavy reusable layers into that image:
+   - Java 17
+   - Android command-line tools
+   - pinned `compileSdk` platform package
+   - pinned build-tools package
+   - seeded Gradle wrapper/plugin cache when practical
+3. bind-mount the project source at runtime so source edits do **not** force SDK reinstall layers to rebuild
+4. run `:app:assembleDebug` without `clean`
+5. copy the real APK to a repo-visible `artifacts/` path
+6. keep the Compose stack alive with a lightweight long-running support service such as an artifact HTTP server
+7. expose at most one loopback-only host port when that support surface is published
+
+This gives `docker compose up --build` a stable healthy state that is both honest and observable.
+
+With the verified lab shape, the Compose command should be treated as acceptable when it:
+
+- reaches healthy artifact-serving state predictably
+- avoids SDK reinstall on reruns
+- avoids default `clean` builds
+- keeps the expensive work in image/toolchain layers and one running container rather than bouncing across multiple heavyweight containers
+
+Avoid the failed pattern of separate Compose build/test containers sharing one mutable Gradle cache volume by default. That strategy easily produces cache-lock contention and does not improve baseline honesty.
+
+If `./run_app.sh` also exists, it should:
+
+1. normalize `JAVA_HOME`
+2. detect `ANDROID_HOME` when available
+3. run `./init_db.sh` when relevant
+4. build a debug APK or equivalent baseline artifact
+5. print the artifact path and any non-sensitive local bootstrap output path when useful
+
+## `./run_tests.sh`
+
+`./run_tests.sh` should be containerized and cover the honest Android broad baseline without requiring an emulator:
+
+- lint
+- assemble
+- JVM tests
+- Robolectric tests only when the verified Docker baseline supports them reliably
+- schema verification when Room is used
+
+Recommended broad-path execution pattern:
+
+1. start the baseline container with `docker compose up --build -d --wait`
+2. reuse that same running container for Gradle verification (`docker compose exec`) so the already-built toolchain state and build outputs are reused
+3. smoke-check the same artifact/support surface that `docker compose up --build` claims to provide
+4. tear the stack down in the script after verification
+
+This avoids avoidable second-pass rebuild loops while still proving both the build and the documented Docker contract.
+
+## Minimal real test floor
+
+At scaffold, include at least:
+
+- one real rule/helper test
+- one real Android-side unit or Robolectric test **when the verified Linux baseline supports it reliably**
+- one real build/lint verification path
+- schema verification when Room is used
+
+If Android-side host-runtime tests are not stable on the truthful Linux baseline, replace that requirement with:
+
+- at least two real scaffold JVM tests tied to shipped Android entrypoint logic
+- real `lint` + `assemble` proof
+- explicit README disclosure that Docker stops short of Robolectric/emulator proof on that baseline
+
+Do not leave the broad path mostly `NO-SOURCE`.
+
+## README floor
+
+`README.md` must already state:
+
+- scaffold status versus implemented product scope
+- Android-only scope
+- required Docker command: `docker compose up --build`
+- broad test command: `./run_tests.sh`
+- host-side helper command: `./run_app.sh` when present
+- bootstrap/setup honesty
+- main module map and entry-point traceability
+- what stable healthy state means for the Docker support surface
+- what the Docker path does **not** prove on Linux
+
+## Common pitfalls
+
+- hardcoded default passwords
+- committed plaintext bootstrap credentials
+- duplicate bootstrap paths in both script and app code
+- unconditional amd64 forcing on arm hosts
+- broad test path with almost no real tests
+- fake emulator/runtime claims
+- `docker compose up --build` that exits immediately after a one-shot build with no stable healthy support surface
+- repeated Gradle or SDK downloads because the Dockerfile copies the entire source tree before caching heavy toolchain layers
+- shared Gradle cache volumes across concurrent containers when a single running container would be enough
+- default `clean` tasks in Docker commands
+- insisting on Robolectric/native host-runtime coverage when it makes the Linux Docker baseline materially less reliable than honest JVM + lint + assemble proof
+
+## Acceptance checklist
+
+Scaffold is acceptable when:
+
+- `docker compose up --build` succeeds
+- `./run_tests.sh` succeeds
+- bootstrap path is single-source and secret-safe
+- schema export and verification are real when relevant
+- README is honest and traceable
+- minimal real scaffold tests exist
+- no plaintext credentials or `.env` artifacts exist in the repo or package
+- the Docker path reaches a stable healthy artifact-serving state in a reasonable amount of time and avoids obvious rebuild loops on reruns

package/assets/slopmachine/scaffold-playbooks/angular-default.md

@@ -0,0 +1,181 @@
+# Angular Default Scaffold Playbook
+
+Use this playbook when the prompt explicitly wants Angular rather than a category-open frontend choice.
+
+## Goal
+
+Create a simple Angular baseline that:
+
+- uses the official Angular CLI bootstrap path
+- pins the working defaults exactly
+- keeps `docker compose up --build` as the runtime contract
+- keeps `./run_tests.sh` as the broad containerized verification path
+- includes minimal real Angular tests without pretending the app is product-complete
+
+Verified lab: `/Users/yohannesakd/code/eaglepoint/demonstration/scaffold-lab/angular-baseline`
+
+## Runtime contract
+
+- required Docker command: `docker compose up --build`
+- required broad test command: `./run_tests.sh`
+- both commands must be real and working
+
+## Official bootstrap path
+
+Angular docs define the local project bootstrap as `ng new [project-name] [options]`.
+The experimentally verified non-interactive baseline here used:
+
+```bash
+npx -y @angular/cli@21.2.7 new angular-baseline --defaults --package-manager npm --skip-git --routing false --style css --ssr false --test-runner vitest
+```
+
+Why this shape:
+
+- official CLI path
+- no SSR, routing, or extra product surface at scaffold time
+- standalone app defaults preserved
+- Angular 21 docs show `vitest` as the default test runner for new projects
+
+## Evidence basis for the defaults
+
+- Angular CLI docs: `ng new` is the official command to create a workspace and initial application.
+- Angular CLI docs: `test-runner` defaults to `vitest` for new projects.
+- Angular version compatibility docs: Angular 21 supports Node `^20.19.0 || ^22.12.0 || ^24.0.0`.
+
+## Safe pinned defaults used in the verified lab
+
+- bootstrap generator: `@angular/cli@21.2.7`
+- Docker base image: `node:24.13.0-alpine3.22`
+- Angular packages: `21.2.8`
+- `@angular/build`: `21.2.7`
+- `@angular/compiler-cli`: `21.2.8`
+- `typescript`: `5.9.3`
+- `vitest`: `4.1.4`
+- `rxjs`: `7.8.2`
+- `tslib`: `2.8.1`
+- `jsdom`: `28.1.0`
+
+Pin exact versions in `package.json` after generation so reruns are deterministic.
+
+## Docker / Compose pattern
+
+Recommended light baseline pattern:
+
+1. **single pinned Node base image** for both runtime and verification
+2. **development target** runs `ng serve --host 0.0.0.0 --port 4200`
+3. **verify target** runs `npm run verify`
+4. **Compose services**
+   - `web` for `docker compose up --build`
+   - `test` behind a `test` profile for disposable verification
+5. **port strategy**
+   - expose only the Angular app port
+   - prefer `127.0.0.1::4200` so local worktrees do not collide
+6. **health strategy**
+   - use a localhost HTTP healthcheck against `/`
+
+This keeps the baseline convergent without adding SSR, nginx, or browser automation.
+
+## Testing baseline
+
+Minimum real testing floor for this playbook:
+
+- Angular unit tests generated from the official starter
+- at least one rendered-content assertion
+- at least one real user interaction assertion (for example, toggling a panel)
+- `npm run verify` that runs tests and production build
+- `./run_tests.sh` that smoke-checks the live app and runs the verify container
+
+Suggested scripts:
+
+- `npm run test:ci`
+- `npm run build`
+- `npm run verify`
+- `./run_tests.sh`
+
+## README floor
+
+`README.md` must already state:
+
+- that this is a baseline scaffold only
+- exact official bootstrap command used
+- required Docker command: `docker compose up --build`
+- broad test command: `./run_tests.sh`
+- exact pinned versions that materially matter
+- what is intentionally included now
+- what is intentionally deferred
+- no `.env` / no secrets policy
+
+## Exact commands actually run in the verified lab
+
+```bash
+npx -y @angular/cli@21.2.7 new angular-baseline --defaults --package-manager npm --skip-git --routing false --style css --ssr false --test-runner vitest
+npm install
+npm run verify
+docker compose up -d --build
+docker compose ps
+docker compose port web 4200
+curl -fsS http://127.0.0.1:<mapped-port>
+docker compose down --remove-orphans
+./run_tests.sh
+python3 - <<'PY'
+import signal
+import subprocess
+import time
+from urllib.request import urlopen
+
+cwd = "/Users/yohannesakd/code/eaglepoint/demonstration/scaffold-lab/angular-baseline"
+proc = subprocess.Popen(["docker", "compose", "up", "--build"], cwd=cwd)
+error = None
+try:
+    deadline = time.time() + 240
+    while time.time() < deadline:
+        try:
+            output = subprocess.check_output(["docker", "compose", "port", "web", "4200"], cwd=cwd, text=True).strip()
+            if output:
+                port = output.rsplit(":", 1)[1]
+                with urlopen(f"http://127.0.0.1:{port}", timeout=2) as response:
+                    if response.status == 200:
+                        print(f"Angular baseline reached while docker compose up --build was active at http://127.0.0.1:{port}")
+                        break
+        except Exception as exc:
+            error = exc
+        time.sleep(2)
+    else:
+        raise RuntimeError(f"Angular baseline never became ready: {error}")
+finally:
+    proc.send_signal(signal.SIGINT)
+    try:
+        proc.wait(timeout=30)
+    except subprocess.TimeoutExpired:
+        proc.kill()
+        proc.wait(timeout=30)
+    subprocess.run(["docker", "compose", "down", "--remove-orphans"], cwd=cwd, check=True)
+PY
+```
+
+## Observed results from the verified lab
+
+- `npm run verify`: passed
+- `docker compose up --build`: reached a live Angular page before controlled shutdown
+- `curl -fsS http://127.0.0.1:<mapped-port>`: returned the HTML shell containing `<title>Angular Baseline Lab</title>`
+- `./run_tests.sh`: passed and printed `Smoke check passed at http://127.0.0.1:<mapped-port>`
+
+## Common pitfalls
+
+- keeping caret ranges instead of exact pins after generation
+- letting Angular's generated README overstate scope
+- skipping containerized smoke proof and only running local tests
+- adding routing, SSR, API clients, or auth before the baseline is verified
+- checking in `.env` even though the scaffold does not need it
+
+## Acceptance checklist
+
+Scaffold is acceptable when:
+
+- `docker compose up --build` works
+- `./run_tests.sh` works
+- minimal real Angular tests exist
+- package and Docker defaults are pinned safely
+- README is honest
+- no `.env` is required or committed
+- the result is experimentally verified, not just theoretically scaffolded

package/assets/slopmachine/scaffold-playbooks/backend-baseline.md

@@ -0,0 +1,142 @@
+# Backend Baseline Scaffold Playbook
+
+Use this playbook when the request is for a category-level backend/API scaffold and the prompt does not already force a different backend family.
+
+## Goal
+
+Create a simple backend baseline that:
+
+- uses an official or safest-known bootstrap path for the selected backend family
+- keeps the runtime contract honest and Docker-first
+- includes a real database dependency and a safe config path
+- exposes one portable broad test command
+- stops at baseline infrastructure instead of product-specific features
+
+## Runtime contract
+
+- required runtime command: `docker compose up --build`
+- required broad test command: `./run_tests.sh`
+- required database bootstrap command when a DB exists: `./init_db.sh`
+- all three commands must be real and working
+
+## Selection matrix for major backend families
+
+| Family | Official / bootstrap path | Strengths | Risks for baseline category work | Decision |
+| --- | --- | --- | --- | --- |
+| Node | `nest new backend-baseline --package-manager npm` | strongest official CLI, batteries included, built-in test scaffolding | heavier config/ORM wiring once safe config and DB state are enforced | good fallback when prompt explicitly asks for Nest or Node enterprise conventions |
+| Python | `python3 -m venv .venv` + pinned install; if available, prefer `uv init backend-baseline` first | fastest API + DB prototype, smallest surface to keep honest, easy Docker/test story | no single dominant framework generator, so some app structure is still hand-wired | **chosen default** |
+| Java | Spring Initializr / `start.spring.io` bootstrap | strongest official generator, production-shaped defaults, rich ecosystem | slower build/test loops, more boilerplate for a neutral category baseline | use when prompt explicitly asks for Spring or JVM enterprise patterns |
+| Go | `go mod init backend-baseline` plus Gin/Chi setup | fast builds, simple container runtime, small deploy footprint | fewer built-in baseline opinions for validation/config/test ergonomics | use when prompt explicitly wants Go or minimal static binaries |
+| PHP | `composer create-project laravel/laravel backend-baseline` or `laravel new backend-baseline` | strong official starter, batteries included, mature testing story | heavier than needed for neutral category baseline; requires PHP/Composer toolchain | use when prompt explicitly asks for Laravel/PHP |
+
+## Chosen default stack and version pins
+
+Prototype and default recommendation:
+
+- Python `3.12`
+- FastAPI `0.122.0`
+- Uvicorn `0.38.0`
+- SQLAlchemy `2.0.44`
+- SQLite `3` via Python stdlib driver
+- pytest `8.4.2`
+- httpx `0.28.1`
+
+Why this default won:
+
+- fastest verified path to a real API + real DB baseline
+- Docker and test setup stay readable instead of framework-heavy
+- works well as a category-level default when the prompt does not already lock the backend family
+
+## Bootstrap rule
+
+- use the official or best-known bootstrap command for the requested backend family when one exists
+- if the prompt leaves the backend family open, default to the Python/FastAPI baseline above
+- after bootstrap, adapt only enough to make Docker runtime, DB wiring, config, and README honest
+
+## Database wiring pattern
+
+- always route the app through one explicit runtime config path such as `APP_CONFIG_PATH=/runtime/config/app-config.json`
+- generate the runtime config file at container startup instead of committing `.env` files
+- for the default prototype, point the app at a SQLite file inside a Docker-managed volume so no DB credentials are needed
+- provide `./init_db.sh` as the single project-standard database setup entrypoint
+- `./init_db.sh` should create the baseline schema or migrations already known at scaffold time
+- when the prompt requires a network DB later, keep the same config-file contract and swap only the database URL and service wiring
+
+## Safe secret/config defaults
+
+- no `.env` dependency
+- no committed secrets
+- runtime secret values generated into Docker-managed volumes or mounted secret files
+- app config should be able to load secrets from file paths rather than only raw environment variables
+- Docker startup must work without user-side exports
+
+## Docker / Compose pattern
+
+- one app service
+- one database strategy: either an embedded DB file for the default fast baseline or a separate DB service when the prompt requires it
+- one test service behind a `test` profile when practical
+- app exposed on `127.0.0.1` only, preferably with a random host port
+- healthchecks on app and database
+- named volumes for runtime-generated config/state instead of committed files
+
+## Testing baseline
+
+At scaffold, include at least:
+
+- one health or smoke endpoint
+- one CRUD-ish endpoint with real persistence
+- containerized `./run_tests.sh`
+- pytest, Jest, JUnit, Go test, or framework-equivalent tests that hit real routes and prove DB wiring
+
+For the chosen Python baseline, the minimum real test floor is:
+
+- `GET /health` proves API boot + DB connectivity
+- `POST /items` then `GET /items` proves real persistence
+- `./run_tests.sh` performs both smoke `curl` checks and containerized pytest execution
+
+## README requirements
+
+`README.md` must already state:
+
+- scaffold status versus implemented scope
+- chosen stack and version pins
+- required runtime command: `docker compose up --build`
+- broad test command: `./run_tests.sh`
+- database bootstrap command: `./init_db.sh`
+- how config is generated safely without `.env`
+- what is intentionally excluded from the baseline
+
+## Verification commands actually run for this prototype
+
+Commands run in `/Users/yohannesakd/code/eaglepoint/demonstration/scaffold-lab/backend-baseline`:
+
+```bash
+docker compose build
+docker compose up --build -d
+docker compose ps
+docker compose port app 8000
+curl -fsS "http://127.0.0.1:32771/health"
+curl -fsS -X POST "http://127.0.0.1:32771/items" -H "content-type: application/json" -d '{"name":"manual-smoke-item"}'
+curl -fsS "http://127.0.0.1:32771/items"
+docker compose down --volumes --remove-orphans
+./run_tests.sh
+```
+
+Observed result:
+
+- app reached healthy state on `127.0.0.1:32771`
+- `./run_tests.sh` finished with `2 passed in 0.49s`
+
+## Known caveats
+
+- this baseline uses schema creation via `./init_db.sh`; upgrade to a migrations tool when the prompt starts evolving the schema over time
+- the verified prototype uses SQLite for speed and zero-secret local startup; switch to a network database when the prompt needs external services, concurrent writers, or production-shaped infra
+- the default stack choice is category-level guidance, not a rule; use the prompt-specific family when it is explicit
+
+## What to reuse later
+
+- Docker-first runtime contract
+- `./run_tests.sh` wrapper pattern
+- `./init_db.sh` as the single DB bootstrap entrypoint
+- config-file-plus-secret-file wiring instead of `.env`
+- health endpoint + one persistence-backed route as the minimum real backend proof

package/assets/slopmachine/scaffold-playbooks/backend-family-matrix.md

@@ -0,0 +1,80 @@
+# Backend Scaffold Family Matrix
+
+Use this matrix after `backend-baseline.md` when the prompt or existing repo indicates a backend/API scaffold and the backend family still needs to be normalized.
+
+## Selection defaults
+
+Follow the original prompt and existing repo first. When the prompt is language-level only, use these defaults:
+
+| Prompt signal | Default family | Why this is the safe default |
+| --- | --- | --- |
+| Node.js | Nest + Fastify | strongest batteries-included Node backend starter, clear module structure, good DB/test story |
+| Python | FastAPI | current playbook default; fastest honest API + DB baseline with low scaffold cost |
+| Java | Spring Boot | strongest official bootstrap and production-shaped defaults |
+| Go | Go + Chi | smallest reliable HTTP surface, easy Docker/runtime wiring, low framework lock-in |
+| PHP | Laravel | strongest official starter, migrations/testing already standardized |
+| `not_specified` | Python + FastAPI | current category-open backend default from `backend-baseline.md` |
+
+If the repo already uses Express, Flask, Django, Gin, or another supported family, keep the repo family unless the prompt explicitly requests migration.
+
+## Shared contract for every backend family
+
+- required runtime command: `docker compose up --build`
+- required broad test command: `./run_tests.sh`
+- required DB bootstrap command when persistence exists: `./init_db.sh`
+- do not depend on a checked-in `.env`
+- generate runtime config into a mounted runtime path such as `APP_CONFIG_PATH=/runtime/config/app-config.json`
+- keep database services internal-only in Compose; publish host ports only when the prompt truly needs direct host access
+- include a real health endpoint plus at least one persistence-backed route or module test
+- wire healthchecks so app startup waits on database readiness when a database service exists
+
+## Supported backend family matrix
+
+| Family | Likely scaffold root / bootstrap command | Safe default direction | Right choice when | Baseline API / test structure expectation | Database composition + shared Docker contract |
+| --- | --- | --- | --- | --- | --- |
+| **Nest + Fastify** (default Node family) | `npx @nestjs/cli@latest new <app-name> --package-manager npm` then `npm install @nestjs/platform-fastify` | Node `22 LTS`, TypeScript `5.x`, Nest `11.x`, Fastify `5.x`; keep Nest CLI layout and switch the HTTP adapter to Fastify | prompt says Node.js only, Nest, modular enterprise API, decorators/DI, or team-scale backend conventions | `src/main.ts`, root module, per-feature `module/controller/service`, unit `*.spec.ts`, e2e `test/*.e2e-spec.ts`, `/health` plus one persistence route | compose with SQLite for smallest local baseline or PostgreSQL for network DB; use Prisma/TypeORM/Drizzle only when chosen explicitly or already present; `./init_db.sh` owns migrations; app stays internal and waits on DB health |
+| **Express + TypeScript** | `npx express-generator@latest <app-name> --no-view` then add TypeScript + test wiring | Node `22 LTS`, Express `5.x`, TypeScript `5.x`; keep the stack thin and explicit | prompt explicitly says Express, webhook/middleware-heavy service, or minimal Node API without Nest ceremony | `src/server.ts` or `src/app.ts`, route modules, service/repository split where needed, `tests/integration/*.test.ts` with Supertest, `/health` plus one persistence route | same Docker contract as Nest; prefer PostgreSQL for service DB, SQLite for smallest local baseline, MongoDB only when the prompt explicitly wants a document store |
+| **FastAPI** (default Python family; experimentally verified) | `uv init <app-name>` then add FastAPI dependencies; fallback `python3 -m venv .venv && pip install fastapi uvicorn[standard] sqlalchemy pytest httpx` | Python `3.12`, FastAPI `0.122.x`, Uvicorn `0.38.x`, SQLAlchemy `2.0.x`, pytest `8.4.x`, httpx `0.28.x` | prompt says Python only, API-first service, typed request/response models, fast neutral backend scaffold | `app/main.py`, router package, config/settings module, DB/session module, `tests/test_health.py` and persistence tests using pytest | default local DB is SQLite in a Docker-managed volume; default network DB is PostgreSQL; keep `APP_CONFIG_PATH` contract, run migrations or schema bootstrap through `./init_db.sh`, and gate app on DB readiness when a DB service exists; see `fastapi-default.md` |
+| **Flask** | `python3 -m venv .venv && pip install Flask SQLAlchemy pytest` | Python `3.12`, Flask `3.1.x`, SQLAlchemy `2.0.x`, pytest `8.4.x`; prefer app-factory structure | prompt explicitly says Flask, simple service/webhook, or very small Python backend without FastAPI/Django weight | `app/__init__.py` app factory, blueprints, DB/extensions module, `tests/` with pytest and Flask test client or httpx, `/health` plus one persistence route | SQLite is acceptable for the minimal baseline; PostgreSQL is the default service DB when a network database is needed; use Alembic or a small idempotent bootstrap in `./init_db.sh` |
+| **Django** (experimentally verified) | `python3 -m pip install "Django>=5.2,<5.3" && django-admin startproject <app-name> . && python manage.py startapp api` | Python `3.12`, Django `5.2.x`; add Django REST Framework only when the scaffold is clearly JSON-API-first | prompt says Django, admin-heavy backend, server-rendered platform, or batteries-included Python monolith | project package + one or more apps, `urls.py`, models, migrations, `tests.py` or `tests/`, `/health` or equivalent readiness view, framework test runner or pytest-django | SQLite is acceptable only for tiny/local baselines; PostgreSQL is the default network DB; use Django migrations via `./init_db.sh`; Compose app should wait on DB health before migrations/start; see `django-default.md` |
+| **Spring Boot** (default Java family; experimentally verified) | `curl -G "https://start.spring.io/starter.tgz" --data-urlencode "type=maven-project" --data-urlencode "language=java" --data-urlencode "javaVersion=21" --data-urlencode "dependencies=web,data-jpa,validation,actuator,testcontainers" --data-urlencode "baseDir=<app-name>" | tar -xz` | Java `21 LTS`, Spring Boot `3.5.x`, Maven wrapper by default, Actuator on, Validation on; prefer explicit config properties and a single app module at scaffold time | prompt says Java only, Spring, JVM enterprise conventions, strong validation/config needs, or production-shaped service baseline | `src/main/java/...` with controller/service/repository split, `src/test/java/...`, `@SpringBootTest` and slice tests, `/actuator/health` plus one persistence-backed API | PostgreSQL is the default network DB; MySQL only when explicit or existing-repo driven; use Flyway or Liquibase for SQL migrations, run through `./init_db.sh`, and keep the DB service internal with healthchecks; see `spring-boot-default.md` |
+| **Go + Chi** (default Go family; experimentally verified) | `go mod init <module-path> && go get github.com/go-chi/chi/v5` | Go `1.24.x`, Chi `5.x`; stay close to `net/http`, `database/sql`, and small explicit packages | prompt says Go only, wants a low-magic service, small binary, or direct control over middleware and DB access | `cmd/server/main.go`, `internal/http`, `internal/store`, `internal/config`, `*_test.go` using `httptest`, `/health` plus one persistence route | SQLite is the local default; PostgreSQL is the default network DB using `pgx` or driver-equivalent; keep migration/bootstrap in `./init_db.sh`; no separate DB host port unless explicitly requested; see `go-chi-default.md` |
+| **Go + Gin** | `go mod init <module-path> && go get github.com/gin-gonic/gin` | Go `1.24.x`, Gin `1.11.x`; use only when the request benefits from higher-level JSON binding/middleware helpers | prompt explicitly says Gin or wants faster handler ergonomics than Chi/stdlib | same structure as Chi, but handlers and middleware hang off Gin router groups; tests still use `httptest` and `go test ./...` | same DB and Docker contract as Chi; do not make MongoDB or Redis the default just because Gin is chosen |
+| **Laravel** (default PHP family; experimentally verified) | `composer create-project laravel/laravel <app-name>` or `laravel new <app-name>` | PHP `8.3+`, Laravel `12.x`; keep built-in config/migration/test structure and queue/cache stubs off unless requested | prompt says PHP only, Laravel, admin/back-office style app, or batteries-included MVC/API backend | `routes/api.php`, controllers, models, migrations, `tests/Feature`, `tests/Unit`, `/up` or `/health` readiness route, real DB-backed feature test | MySQL is the conventional default service DB for PHP-only asks; PostgreSQL is also supported when the repo or prompt wants it; SQLite is fine for tiny local/test baselines; Eloquent migrations run through `./init_db.sh`; DB stays on an internal Compose network; see `laravel-default.md` |
+
+## Practical family guidance
+
+- **Prefer Nest + Fastify over Express** when the prompt only says Node.js and does not push for minimalism.
+- **Prefer FastAPI over Flask or Django** when the prompt only says Python and the task is an API/backend scaffold.
+- **Prefer Django over FastAPI** only when the prompt implies Django conventions, admin-heavy behavior, or server-rendered/backend-monolith shape.
+- **Prefer Chi over Gin** when the prompt only says Go and does not need extra framework ergonomics.
+- **Prefer Laravel over custom PHP wiring** for every PHP-only baseline unless an existing repo already chose a different PHP framework.
+
+## Verified concrete playbooks
+
+- `backend-baseline.md` — verified category-open backend baseline
+- `fastapi-default.md` — experimentally verified FastAPI baseline
+- `spring-boot-default.md` — experimentally verified Spring Boot baseline
+- `django-default.md` — experimentally verified Django baseline
+- `laravel-default.md` — experimentally verified Laravel baseline
+- `go-chi-default.md` — experimentally verified Go + Chi baseline
+
+## Placeholder handling
+
+- `backend_family=not_specified` means **choose from the language default table above**, not “invent a new framework.”
+- `backend_language=not_specified` and no existing repo evidence means **Python + FastAPI**.
+- `backend_family=not_specified` with an existing repo means **keep the existing repo family**.
+- `database=not_specified` should not remove persistence entirely; pair the chosen backend family with the default database module from `database-module-matrix.md`.
+
+## Family-by-family default DB pairing summary
+
+| Family | Local / smallest honest DB default | Network / service DB default |
+| --- | --- | --- |
+| Nest + Fastify | SQLite | PostgreSQL |
+| Express + TypeScript | SQLite | PostgreSQL |
+| FastAPI | SQLite | PostgreSQL |
+| Flask | SQLite | PostgreSQL |
+| Django | SQLite only for tiny local baseline | PostgreSQL |
+| Spring Boot | SQLite only if the prompt truly keeps things local and tiny | PostgreSQL |
+| Go + Chi / Gin | SQLite | PostgreSQL |
+| Laravel | SQLite for tiny local/test baseline | MySQL |