local-dev-stack

The operational half of an ENV-selected local+prod stack: the stage-file layout on disk, the committed-vs-secret split, the process orchestration that boots the stack in dependency order, the local-Supabase port block that lets several stacks coexist on one machine, and the DB post-schema ordering that keeps supabase start booting clean. It is the counterpart to skills/runtime-env-config — that skill is the app-side chain (@cogs/config loader → process.env → EnvProvider → client); this skill is everything around it.

The stack

• Stage files by ENV. .env + .env.<stage> committed (non-secret), .env.<stage>.local gitignored (secrets). Split by the env registry's type — only type:'public' is committed; connection/secret/unknown stay .local. ENV ∈ {dev, test, staging, prod}, never local.
• .gitignore negation. A broad .env* ignore plus a last-match-wins negation that re-includes .env.<stage> while keeping *.local/*.bak out.
• process-compose.yml, not a Procfile. Ordered and dependency-gated: supabase → db:push → db:post → seed → seed-auth → api+web, ENV=dev global, DDL over the direct connection (DATABASE_DIRECT_URL).
• Seed auth users via the admin API. A seed:auth step creates local demo auth.users (email_confirm:true) and keys public.users + memberships to the returned uid, so a login resolves org+role; idempotent and localhost-guarded.
• Per-repo Supabase port block. Each repo picks a distinct 54N2x block + project_id in supabase/config.toml so multiple stacks run at once; the local DATABASE_URL uses the direct db port, not the pooler.
• DB post-schema ordering. RLS / grants / an auth hook that read app tables move OUT of supabase/migrations (which supabase start runs before the schema exists) into an idempotent db:post step that runs after db:push/db:migrate — locally and in prod. Prod keeps RLS.
• Prod parity. Same image, ENV=prod, Supabase Cloud; config.toml ports are local-only; platform-injected secrets beat files (override:false).

Use it

Read SKILL.md for the 10 invariants (one verifiable todo each) and the red flags. Invariant 4's references/port-blocks.md covers TWO port axes: local Supabase (54N2x) and the app's own WEB_PORT/API_PORT — both need a per-repo block, confirmed by a real collision, not just Supabase's. Copy the genericized templates from references/:

• process-compose.yml — the ordered stack.
• apply-post-schema.ts — the db:post runner (idempotent, direct connection).
• gitignore-block.txt — the .env* ignore + negation block.
• env-split.mjs — the conservative registry-type splitter (node env-split.mjs --registry <path> --in <source.env> --stage dev --dry-run).
• port-blocks.md — the 54N2x allocation table + direct-vs-pooler note.
• seed-auth.ts — the seed:auth step: local demo auth.users via the admin API, keyed to the app rows, idempotent, localhost-guarded.

Swap the <scope> / <app> / <stage> placeholders for your own.

Companion

Pairs with skills/runtime-env-config (the loader + EnvProvider chain that reads the stage files this skill lays out) and the canonical schema in docs/ENVIRONMENT-CONFIG.md.