Foundation: validate template/ against scaffold.md §13 checklist

Follow-up to #14. The template/ scaffold is locally complete (commit ef90202) but no part of it has been executed end-to-end — the standards-repo devcontainer is Python-only and cannot run pnpm/uv/docker. This issue tracks the §13 verification gate. ## Validate where Run validation in the **template's own polyglot devcontainer**, NOT in this standards-repo devcontainer. Two equivalent paths: - **(a) Forge round-trip**: push template/ to the separate `ai-development-stack-template` repo on the forge → clone fresh → "Reopen in container" → VS Code builds template/.devcontainer/ → run the checklist below. Also exercises the "Use this template" flow end-to-end. - **(b) Local subworkspace**: open `/path/to/ai-development-stack/template/` as a separate VS Code workspace **from the host** (not from inside the standards-repo devcontainer) → VS Code finds template/.devcontainer/ → run the checklist below. Skips the forge round-trip. (c) is explicitly NOT to make the standards-repo devcontainer polyglot — keep that one Python-only; the standards repo is a meta-repo, the template owns its own runtime. ## scaffold.md §13 checklist (the actual gate) Run these in order, in a clean checkout: - [ ] `pnpm install` from a fresh clone succeeds (resolves all pinned versions) - [ ] `docker compose -f .devcontainer/docker-compose.yml up -d postgres` and `pnpm db:migrate` (or `uv run alembic upgrade head`) succeeds - [ ] `pnpm dev` boots both apps; web reaches api at `/health` - [ ] Auth flow works: register → login → call a protected endpoint → 200 - [ ] OTel traces appear in console with no env vars set; no errors - [ ] `pnpm typecheck` and `pnpm test` pass with zero warnings - [ ] Claude Code, given AGENTS.md, can add a new domain end-to-end (router, schemas, models, service, migration, frontend page, generated types, tests) in a single session without violating any AGENTS.md rules - [ ] `bootstrap.sh` runs cleanly with each forge choice (tea / gh / glab / none) and each lane (typescript / python) - [ ] `bootstrap.sh` writes a sensible AGENTS.md "Forge" block per choice ## Pinning verification (resolves cleanly against real registries) - [ ] `drizzle-orm@1.0.0-beta.22` and `drizzle-kit@1.0.0-beta.22` resolve on npm - [ ] `better-auth@1.1.5` resolves on npm - [ ] All `@opentelemetry/*` versions in apps/web and apps/api-typescript-template resolve compatibly - [ ] `tea 0.14.0`, `glab 1.49.0` download URLs in .devcontainer/Dockerfile still work (these will rot) - [ ] uv installer URL `https://astral.sh/uv/install.sh` still works - [ ] `@hey-api/openapi-ts@0.64.0` resolves on npm - [ ] All Python deps in apps/api-python-template/pyproject.toml resolve via `uv sync` ## Known small fixes to apply during validation - [ ] `apps/api-python-template/src/api/auth/router.py` has a `... if False else None` placeholder that won't pass `ruff` cleanly — replace with a comment block - [ ] `apps/api-python-template/alembic.ini` `post_write_hooks = ruff` requires `uv` on PATH at migration-author time — confirm this is reliably true inside the polyglot devcontainer - [ ] TanStack Router's `routeTree.gen.ts` is gitignored; first `pnpm typecheck` fails on a clean checkout until `pnpm dev`/`pnpm build` runs once. Either add a `pnpm prebuild` script that runs `tsr generate`, or document it in apps/web/AGENTS.md. - [ ] `bootstrap.sh` non-interactive default-to-TS edge case: if `entrypoint.sh` runs bootstrap headless and `BOOTSTRAP_LANE` isn't exported, the Python lane is silently deleted with no recovery. Decide: refuse to proceed in non-TTY mode without explicit lane, or print loud warning before destroying the unused lane dir. ## Out of scope - Recipes #1–#13 (`docs/recipes/*.md` content) — separate issues, can proceed in parallel. - `template/docs/observability.md` — referenced from AGENTS.md but not yet written; flag during validation but track separately. - Pushing to the actual `ai-development-stack-template` forge repo — that's the remaining work item from #14 and gates on this issue passing. ## Done when The §13 checklist is fully green from a fresh clone of template/ (whether from the forge or the local subworkspace), pinning checks pass, and the small fixes are in. At that point #14's last work item (create + push the forge template repo) is unblocked.

jbr870 commented

2026-05-04 14:25:51 +00:00

Owner

Follow-up to #14. The template/ scaffold is locally complete (commit ef90202) but no part of it has been executed end-to-end — the standards-repo devcontainer is Python-only and cannot run pnpm/uv/docker. This issue tracks the §13 verification gate.

Validate where

Run validation in the template's own polyglot devcontainer, NOT in this standards-repo devcontainer. Two equivalent paths:

(a) Forge round-trip: push template/ to the separate ai-development-stack-template repo on the forge → clone fresh → "Reopen in container" → VS Code builds template/.devcontainer/ → run the checklist below. Also exercises the "Use this template" flow end-to-end.
(b) Local subworkspace: open /path/to/ai-development-stack/template/ as a separate VS Code workspace from the host (not from inside the standards-repo devcontainer) → VS Code finds template/.devcontainer/ → run the checklist below. Skips the forge round-trip.

(c) is explicitly NOT to make the standards-repo devcontainer polyglot — keep that one Python-only; the standards repo is a meta-repo, the template owns its own runtime.

scaffold.md §13 checklist (the actual gate)

Run these in order, in a clean checkout:

pnpm install from a fresh clone succeeds (resolves all pinned versions)
docker compose -f .devcontainer/docker-compose.yml up -d postgres and pnpm db:migrate (or uv run alembic upgrade head) succeeds
pnpm dev boots both apps; web reaches api at /health
Auth flow works: register → login → call a protected endpoint → 200
OTel traces appear in console with no env vars set; no errors
pnpm typecheck and pnpm test pass with zero warnings
Claude Code, given AGENTS.md, can add a new domain end-to-end (router, schemas, models, service, migration, frontend page, generated types, tests) in a single session without violating any AGENTS.md rules
bootstrap.sh runs cleanly with each forge choice (tea / gh / glab / none) and each lane (typescript / python)
bootstrap.sh writes a sensible AGENTS.md "Forge" block per choice

Pinning verification (resolves cleanly against real registries)

drizzle-orm@1.0.0-beta.22 and drizzle-kit@1.0.0-beta.22 resolve on npm
better-auth@1.1.5 resolves on npm
All @opentelemetry/* versions in apps/web and apps/api-typescript-template resolve compatibly
tea 0.14.0, glab 1.49.0 download URLs in .devcontainer/Dockerfile still work (these will rot)
uv installer URL https://astral.sh/uv/install.sh still works
@hey-api/openapi-ts@0.64.0 resolves on npm
All Python deps in apps/api-python-template/pyproject.toml resolve via uv sync

Known small fixes to apply during validation

apps/api-python-template/src/api/auth/router.py has a ... if False else None placeholder that won't pass ruff cleanly — replace with a comment block
apps/api-python-template/alembic.ini post_write_hooks = ruff requires uv on PATH at migration-author time — confirm this is reliably true inside the polyglot devcontainer
TanStack Router's routeTree.gen.ts is gitignored; first pnpm typecheck fails on a clean checkout until pnpm dev/pnpm build runs once. Either add a pnpm prebuild script that runs tsr generate, or document it in apps/web/AGENTS.md.
bootstrap.sh non-interactive default-to-TS edge case: if entrypoint.sh runs bootstrap headless and BOOTSTRAP_LANE isn't exported, the Python lane is silently deleted with no recovery. Decide: refuse to proceed in non-TTY mode without explicit lane, or print loud warning before destroying the unused lane dir.

Out of scope

Recipes #1–#13 (docs/recipes/*.md content) — separate issues, can proceed in parallel.
template/docs/observability.md — referenced from AGENTS.md but not yet written; flag during validation but track separately.
Pushing to the actual ai-development-stack-template forge repo — that's the remaining work item from #14 and gates on this issue passing.

Done when

The §13 checklist is fully green from a fresh clone of template/ (whether from the forge or the local subworkspace), pinning checks pass, and the small fixes are in. At that point #14's last work item (create + push the forge template repo) is unblocked.

Rows
Columns

Foundation: validate template/ against scaffold.md §13 checklist #15