Kickstart

Use this as the default workflow when starting work in this repo.

Workflow

Skim docs/START_HERE.md (if new), docs/INDEX.md, and relevant items in docs/todo/.
Check for scoped rules in nested AGENTS.md files (e.g. dbal/AGENTS.md) before editing those areas.
Use the prompts in .github/prompts/ as needed:
- Plan: 1-plan-feature.prompt.md
- Design: 2-design-component.prompt.md
- Implement: 3-impl-*.prompt.md
- Test: 4-test-*.prompt.md
- Review: 5-review-code.prompt.md
- Deploy: 6-deploy-*.prompt.md
- Maintain: 7-maintain-*.prompt.md
- Docs: 8-docs-feature.prompt.md
Keep changes small and follow existing patterns; avoid dependency churn.

Next.js app: frontends/nextjs/ (source in src/, E2E in e2e/, local scripts in scripts/).
Component packages: packages/ (seed JSON under packages/*/seed/, optional static_content/, schema checks in packages/*/tests/).
DBAL: dbal/ (TypeScript library in dbal/ts/).
Prisma schema/migrations: prisma/ (schema.prisma, migrations/).
Shared config: config/ (symlinked into frontends/nextjs/).
Repo utilities: tools/ (quality checks, workflow helpers, code analysis).

Run app workflows from frontends/nextjs/:

Install: npm ci (or npm install)
Dev: npm run dev
Build/serve: npm run build / npm run start
Lint: npm run lint / npm run lint:fix
Typecheck: npm run typecheck
Unit: npm run test:unit / npm run test:coverage
Function coverage: npm run test:check-functions
Coverage report: npm run test:coverage:report
E2E: npm run test:e2e
Prisma (schema in prisma/schema.prisma, config in frontends/nextjs/prisma.config.ts):
- First-time setup: copy .env.example to .env (or ensure DATABASE_URL is set)
- Commands: npm run db:generate / npm run db:push / npm run db:migrate
- Validate: npx prisma validate
Coverage output: frontends/nextjs/coverage/

DBAL workflows live in dbal/ts/ (npm run build, npm run test:unit).

TypeScript + ESM. Prefer @/… imports inside frontends/nextjs/src/.
React components: PascalCase.tsx; hooks: useThing.ts; tests: *.test.ts(x).
Unit tests: frontends/nextjs/src/**/*.test.ts(x) and packages/*/tests/*.test.ts; E2E: frontends/nextjs/e2e/.
Prefer one focused function (“lambda”) per file; use classes only as containers for related functions (see .github/prompts/LAMBDA_PROMPT.md).
Add/adjust tests with behavior changes; keep tests deterministic (no network, stable clocks/IDs), and parameterize where it improves coverage (it.each()); keep source↔test naming aligned.
Leave TODOs only when you’re explicitly deferring follow-up work (and include the next step).

Commit as you go with descriptive (Conventional Commit-style) messages; default to trunk-based work on main unless a PR flow is required.
If multiple agents are working, merge/rebase carefully and avoid overwriting each other’s changes.
Before opening a PR, run npm run lint, npm run typecheck, and the relevant tests (from frontends/nextjs/).
PRs should include: what/why, linked issue (if any), screenshots for UI changes, and notes on DB/schema changes.

Prefer data-driven config (JSON/Lua) over hard-coded TS/TSX; start with packages/*/seed/ and docs/architecture/data-driven-architecture.md.
Prefer declarative UI via RenderComponent / generic renderers (see docs/architecture/generic-page-system.md).
Route data access through DBAL / the Database wrapper (frontends/nextjs/src/lib/db/ or @/lib/db); don’t bypass it.
Assume multi-tenancy: include tenantId filtering and isolate per-tenant data.
UI uses Material UI (@mui/*) and SCSS/modules as needed; don’t introduce Radix UI or Tailwind. See docs/RADIX_TO_MUI_MIGRATION.md and UI_STANDARDS.md.
Package metadata: keep packages/*/seed/metadata.json packageId in snake_case and versions semver (e.g. 1.2.3).

Use act to reproduce and debug GitHub Actions locally (from frontends/nextjs/: npm run act, npm run act:diagnose; see docs/guides/ACT_TESTING.md).

If you get stuck, see .github/prompts/EEK-STUCK.md.