jbr870/ai-development-stack
1
0
Fork 0
Code Issues 15 Pull requests Projects Releases Packages Wiki Activity Actions

Foundation: scaffold template repo for new projects #14

New issue
Open
opened 2026-05-04 13:28:03 +00:00 by jbr870 · 0 comments
jbr870 commented 2026-05-04 13:28:03 +00:00
Owner
Copy link

Create a new Forgejo template repo ai-development-stack-template that produces a working starter project on first devcontainer boot. This standards repo stays as docs/decisions; the template repo is the seed for new projects.

Decisions

Devcontainer model. Separate template repo on the forge, marked as a Forgejo template. New-project flow: Use this template on Forgejo → clone → reopen in container → bootstrap.sh runs once on first boot. Existing-project flow uses recipes (#1–#13) inside the running container.

Pinning model — tiered by upstream stability:

  • Exact-pin wobbly upstreams: Drizzle 1.0.0-beta.X (already mandated), Better-Auth, Mastra, Astro 6, TanStack Start when adopted, anything pre-1.0.
  • Caret-pin stable cores: React, Tailwind, Vite, FastAPI, Pydantic, SQLAlchemy, Hono, TanStack Router/Query, Zod, Vitest, ruff, biome, pyright, uv.
  • Docker/compose images: pin major+minor (node:24-bookworm, postgres:16-alpine, python:3.12-bookworm). Never latest.
  • Lockfiles always committed: pnpm-lock.yaml, uv.lock. Reproducibility comes from lockfiles, not from manual exact-pins everywhere.

Renovate. Deferred pending user research into long-term legitimacy. Template will not ship with renovate.json for now; revisit once direction is set.

Work items

  • Create ai-development-stack-template repo on the forge, marked as a Forgejo template.
  • Devcontainer (project-template variant, polyglot): Dockerfile with Node 24 LTS + pnpm + Python 3.12 + uv; docker-compose.yml with sibling Postgres + pgvector and OTel collector hooks; .env.example; entrypoint.sh running bootstrap.sh on first boot; idempotency sentinel. Differs from this standards repo's devcontainer (Python-only) — needs polyglot.
  • Root config files (scaffold.md §3): package.json (workspaces), pnpm-workspace.yaml, turbo.json, biome.json, compose.yaml, .env.example, root pyproject.toml (for Python-lane projects' uv workspace).
  • Root AGENTS.md (§4): seeded from scaffold.md §4 prose; placeholders for project-name, lane choice, optional add-ons.
  • apps/web template (§5): React 19 + Vite + TanStack Router/Query + Tailwind v4 + shadcn/ui + Sentry + OTel; per-app AGENTS.md.
  • apps/api TS-lane template (§6, default lane): Hono + Drizzle (pinned beta) + Better-Auth + Zod v4 + OTel Node SDK; per-app AGENTS.md; Dockerfile.
  • apps/api Python-lane template (§7, alternative lane): FastAPI + Pydantic v2 + SQLAlchemy 2.0 async + Alembic + alembic-utils + PyJWT + pwdlib + FastAPI-Users (scaffolding-only) + Authlib + OTel auto-instrumentation; per-app AGENTS.md; production Dockerfile.
  • .claude/ scaffolding (§8): per-project skills, .mcp.json, .claude/settings.json hooks, plugins config.
  • bootstrap.sh (first-boot script): project-rename, lane prompt (defaults to TS lane unless flag), pnpm install, pnpm dlx @tanstack/intent install --yes (per scaffold.md:945), uv sync if Python-lane, sentinel-guarded for idempotency.

References

  • Standards: docs/standard.md, docs/scaffold.md in this repo
  • Recipes (post-foundation work): issues #1–#13 in this repo
  • Devcontainer reference: this repo's .devcontainer/ (will need polyglot extension)
  • Bootstrap reference: scaffold.md:945

Recipes #1–#13 are unblocked

The recipe-extraction issues don't strictly depend on this foundation — scaffold.md §10 is unambiguous prose that can be extracted without a working template. They become useful only once a template exists, but the extraction work itself can proceed in parallel.

Create a new Forgejo template repo `ai-development-stack-template` that produces a working starter project on first devcontainer boot. This standards repo stays as docs/decisions; the template repo is the seed for new projects. ## Decisions **Devcontainer model.** Separate template repo on the forge, marked as a Forgejo template. New-project flow: *Use this template* on Forgejo → clone → reopen in container → `bootstrap.sh` runs once on first boot. Existing-project flow uses recipes (#1–#13) inside the running container. **Pinning model — tiered by upstream stability:** - **Exact-pin** wobbly upstreams: Drizzle `1.0.0-beta.X` (already mandated), Better-Auth, Mastra, Astro 6, TanStack Start when adopted, anything pre-1.0. - **Caret-pin** stable cores: React, Tailwind, Vite, FastAPI, Pydantic, SQLAlchemy, Hono, TanStack Router/Query, Zod, Vitest, ruff, biome, pyright, uv. - **Docker/compose images**: pin major+minor (`node:24-bookworm`, `postgres:16-alpine`, `python:3.12-bookworm`). Never `latest`. - **Lockfiles always committed**: `pnpm-lock.yaml`, `uv.lock`. Reproducibility comes from lockfiles, not from manual exact-pins everywhere. **Renovate.** Deferred pending user research into long-term legitimacy. Template will not ship with `renovate.json` for now; revisit once direction is set. ## Work items - [ ] Create `ai-development-stack-template` repo on the forge, marked as a Forgejo template. - [ ] **Devcontainer** (project-template variant, polyglot): Dockerfile with Node 24 LTS + pnpm + Python 3.12 + uv; `docker-compose.yml` with sibling Postgres + pgvector and OTel collector hooks; `.env.example`; `entrypoint.sh` running `bootstrap.sh` on first boot; idempotency sentinel. Differs from this standards repo's devcontainer (Python-only) — needs polyglot. - [ ] **Root config files** (`scaffold.md` §3): `package.json` (workspaces), `pnpm-workspace.yaml`, `turbo.json`, `biome.json`, `compose.yaml`, `.env.example`, root `pyproject.toml` (for Python-lane projects' uv workspace). - [ ] **Root `AGENTS.md`** (§4): seeded from `scaffold.md` §4 prose; placeholders for project-name, lane choice, optional add-ons. - [ ] **`apps/web` template** (§5): React 19 + Vite + TanStack Router/Query + Tailwind v4 + shadcn/ui + Sentry + OTel; per-app `AGENTS.md`. - [ ] **`apps/api` TS-lane template** (§6, default lane): Hono + Drizzle (pinned beta) + Better-Auth + Zod v4 + OTel Node SDK; per-app `AGENTS.md`; Dockerfile. - [ ] **`apps/api` Python-lane template** (§7, alternative lane): FastAPI + Pydantic v2 + SQLAlchemy 2.0 async + Alembic + alembic-utils + PyJWT + pwdlib + FastAPI-Users (scaffolding-only) + Authlib + OTel auto-instrumentation; per-app `AGENTS.md`; production Dockerfile. - [ ] **`.claude/` scaffolding** (§8): per-project skills, `.mcp.json`, `.claude/settings.json` hooks, plugins config. - [ ] **`bootstrap.sh`** (first-boot script): project-rename, lane prompt (defaults to TS lane unless flag), `pnpm install`, `pnpm dlx @tanstack/intent install --yes` (per `scaffold.md:945`), `uv sync` if Python-lane, sentinel-guarded for idempotency. ## References - Standards: `docs/standard.md`, `docs/scaffold.md` in this repo - Recipes (post-foundation work): issues #1–#13 in this repo - Devcontainer reference: this repo's `.devcontainer/` (will need polyglot extension) - Bootstrap reference: `scaffold.md:945` ## Recipes #1–#13 are unblocked The recipe-extraction issues don't strictly depend on this foundation — `scaffold.md` §10 is unambiguous prose that can be extracted without a working template. They become *useful* only once a template exists, but the extraction work itself can proceed in parallel.
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
No results found.
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
jbr870/ai-development-stack#14
No description provided.